21 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT
The following subprograms are available for saving YBOS
arrays on disc, restoring them from disc and for accessing
individual banks or lists of banks from disc. Note that these
subprograms allow multiple files to be open simultaneously.
BDSAVE Dump YBOS Array to Discfile
BDREST Restore YBOS array from Discfile
BDOPEN Open Discfile for reading
BDCLOS Close previously opened Discfile
BDRBNK Read Single Bank from discfile
BDRLST Read Banks or List of banks from discfile
BDRNUM Read Specified Banks from discfile
BDWBNK Write Single Bank to discfile
BDWLST Write Banks or List of banks to discfile
BDWNUM Write Specified Banks to discfile
BDUNIT Specify new Logical Unit No. for Disc
BDRECL Specify new Record Length for Disc I/O
BDLIST Modify bank set with all names on disk
BDNLST Return a list of all banks of a given name on disk
BDNEAR Find first bank of given name with number greater that
some threshold.
BDBGST Find the largest bank number for a given name on disk.
BDSMLL Find the smallest bank number for a given name on disk.
BDJRNL Enable/disable file journaling.
BDSEAR Search A disk file for a target bank.
21.1 BDSAVE - Save YBOS Array Named Bank Region on Discfile
This subprogram writes the specified YBOS array named
bank region to the specified Discfile.
Calling Sequence
STATUS = BDSAVE(JW,FILNAM)
Input Parameters
JW YBOS array
FILNAM (Character) Discfile Name
Output Parameters
None
Function Value
BDSAVE (Integer) YESUCC Success
YEILUN Illegal Unit Number
> 0 Standard VAX/VMS
Error Code
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The standard Logical Unit Number with which the data
is written is 30. This may be changed via a call to
BDUNIT.
3. The standard record length can be changed via a call
to BDRECL.
4. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.2 BDREST - Restore YBOS Array Named Bank Region from
Discfile
This subprogram restores the specified YBOS array named
bank region from the specified Discfile.
Calling Sequence
STATUS = BDREST(JW,NDIM,FILNAM)
Input Parameters
JW YBOS array
NDIM (Integer) The Size of the Array
(In Integer words)
FILNAM (Character) The Discfile Name
Output Parameters
None
Function Value
BDREST (Integer) YESUCC Success
YEILUN Illegal Unit Number
YEOVRF Insufficient Space
> 17 Standard VAX/VMS
Error Code
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array. Any previous
information in this array will be lost.
2. It is not necessary that the size of the array JW
(given by NDIM) be identical to that of the original
array from which the discfile was created. However,
an error return will be taken if the specified array
is too small. In this case the user should not
assume that the array is correctly setup.
3. On completion of this call the status of the named
banks in JW is essentially identical to that of the
original array at the time it was written to disc via
BDSAVE (except for any length differences). The user
may manipulate banks as normal.
4. The standard Logical Unit Number with which the data
is read is 30. This may be changed via a call to
BDUNIT.
5. The Illegal Logical Unit Error indicates that a
discfile is already opened (via BDOPEN) on the
currently setup YBOS disc logical unit number. The
user should correct the fault by using BDUNIT.
6. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.3 BDOPEN - Open Discfile for YBOS I/O
This subprogram opens the specified discfile such that
individual banks, or lists of banks may be read from it or
written to it.
Calling Sequence
STATUS = BDOPEN(JW,LUNIT,FILNAM,CREATE,RCLEN)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical Unit No.
FILNAM (Character) Discfile Name
CREATE (Integer) Create file
RCLEN (Integer) File record length
Output Parameters
None
Function Value
BDOPEN (Integer) YESUCC Success
YEILUN Illegal Unit Number
YEOVRF Insufficient Space
> 0 Standard VAX/VMS
Error Code
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. This call creates bank (name)"+DSK" (number)"LUNIT"
containing pointers to binary search work banks used
to locate named banks on the diskfile. This Data
structure is refered to as the diskfile dictionary.
3. If the specified Logical Unit already has an opened
file (via BDOPEN), then it will be closed.
4. If the diskfile dictionary from a previous BDOPEN has
been saved on disk by BDCLOS, BDOPEN will, by
default, read it from disk rather than build it from
scratch.
5. If CREATE equals 1, the a new file is created if no
file exists.
6. RCLEN is the file record length in longwords.
7. The following BOPTN options are available:
BOPTN(JW,OPTION) OPTION = 1 --> Open file readonly
OPTION = 2 --> Build disk dictionary, rather
than read it from disk
OPTION = 3 --> Readonly and Build
8. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.4 BDCLOS - Close Discfile
This subprogram closes the currently opened Discfile.
Calling Sequence
STATUS = BDCLOS(JW,LUNIT)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical Unit No.
Output Parameters
None
Function Value
BDCLOS (Integer) YESUCC Success
YEILUN Illegal Unit Number
N.B.
1. The JW array should correspond to that used in the
previous call to BDOPEN.
2. To save the diskfile dictionary (see BDOPEN) call
BOPTN with option equal 1 just before the BDCLOS
call.
3. Once the diskfile dictionary has been saved by
BDCLOS, all subsequent BDCLOS calls for that file
will automatically save the dictionary.
4. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.5 BDRBNK - Read a Single YBOS Bank from Discfile
This subprogram reads the specified YBOS bank from the
currently opened (via BDOPEN) discfile into the specified YBOS
array.
Calling Sequence
STATUS = BDRBNK(JW,LUNIT,NAME,NR,IND)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical Unit No.
NAME (Character) Bank Name
NR (Integer) Bank Number
Output Parameters
IND (Integer) Index to the Bank
(or zero if non-existent)
Function Value
BBRBNK (Integer) YESUCC Success
YEILUN Illegal Unit Number
YENOBK Non-existent Bank
YEOVRF Insufficient Space
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The JW array should correspond to that used in the
previous call to BDOPEN with this Logical Unit No.
3. If the specified Bank already exists then it will be
deleted before performing the read from disc.
4. If NR is negative, then BDRBNK will read the lowest
numbered Bank with the specified Bank Name from the
discfile. The actual number of this Bank may be
determined using the BNUMB routine described
elsewhere.
5. The YENOBK Return is informational only, no Error
Message being reported.
6. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.6 BDRLST - Read Banks or List of Banks from Disc
This subprogram reads all the banks with the specified
Bank Name, or all Banks in the specified List of names, from
the Discfile.
Calling Sequence
STATUS = BDRLST(JW,LUNIT,LIST)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical Unit No.
LIST (Character) Set name or bank list
Output Parameters
None
Function Value
BDRBNK (Integer) YESUCC Success
YEILUN Illegal Unit Number
YEOVRF Insufficient Space
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The JW array should correspond to that used in the
previous call to BDOPEN with the specified Logical
Unit No.
3. If any of the specified banks already exist they will
be deleted before performing the read from disc.
4. The LIST parameter may be either a single letter bank
set name, "*" for all bank names, or a list of
4-character bank names (e.g. ANDYBERTCARLDAVE). In
any case, all banks with the specified name or names
(but differing bank numbers) will be read.
5. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.7 BDRNUM - Read Banks from Disc
This subprogram reads all the specified banks (having the
specified Bank Name and Numbers as given in the array) from
the Discfile.
Calling Sequence
STATUS = BDRNUM(JW,LUNIT,NAME,LIST,NUMB)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical Unit No.
NAME (Character*4) Bank Name
LIST (Integer Array) Array of Bank numbers
NUMB (Integer) Length of LIST Array
Output Parameters
None
Function Value
BDRNUM (Integer) YESUCC Success
YEILUN Illegal Unit Number
YEOVRF Insufficient Space
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The JW array should correspond to that used in the
previous call to BDOPEN with the specified Logical
Unit No.
3. If any of the specified banks already exist they will
be deleted before performing the read from disc.
4. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.8 BDWBNK - Write a single YBOS Bank to Discfile
This subprogram writes the specified YBOS bank from the
specified YBOS array to the currently opened (via BDOPEN)
discfile.
Calling Sequence
STATUS = BDWBNK(JW,LUNIT,NAME,NR,IND)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical Unit No.
NAME (Character) Bank Name
NR (Integer) Bank Number
Output Parameters
IND (Integer) Index to the Bank
(or zero if non-existent)
Function Value
BDWBNK (Integer) YESUCC Success
YEILUN Illegal Unit Number
YEOVRF Insufficient Space
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The JW array should correspond to that used in the
previous call to BDOPEN with the specified Logical
Unit No.
3. The specified Bank should have the same
characteristics as the bank already residing on disc.
4. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.9 BDWLST - Write Banks or List of Banks to Disc
This subprogram writes all the banks with the specified
Bank Name, or all Banks in the specified List of names, to the
Discfile.
Calling Sequence
STATUS = BDWLST(JW,LUNIT,LIST)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical Unit No.
LIST (Character) Set name or bank list
Output Parameters
None
Function Value
BDWLST (Integer) YESUCC Success
YEILUN Illegal Unit Number
YEOVRF Insufficient Space
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The JW array should correspond to that used in the
previous call to BDOPEN with the specified Logical
Unit No.
3. The LIST parameter may be either a single letter bank
set name, "*" for all bank names, or a list of
4-character bank names (e.g. ANDYBERTCARLDAVE). In
any case, all banks with the specified name or names
(but differing bank numbers) will be written.
4. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.10 BDWNUM - Write Banks to Disc
This subprogram writes all the specified banks to the
Discfile.
Calling Sequence
STATUS = BDWNUM(JW,LUNIT,NAME,LIST,NUMB)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical Unit No.
NAME (Character*4) Bank Name
LIST (Integer Array) Array of bank numbers
NUMB (Integer) Length of LIST Array
Output Parameters
None
Function Value
BDWNUM (Integer) YESUCC Success
YEILUN Illegal Unit Number
YEOVRF Insufficient Space
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The JW array should correspond to that used in the
previous call to BDOPEN with the specified Logical
Unit No.
3. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.11 BDUNIT - Specify new Logical Unit for Disc I/O
This subprogram specifies a new Logical Unit Number for
all subsequent BDSAVE or BDREST operations.
Calling Sequence
STATUS = BDUNIT(JW,LUNIT)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical Unit Number
Output Parameters
None
Function Value
BDUNIT (Integer) YESUCC Success
YEILUN Illegal Unit Number
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. A Logical Unit of 0 will cause the default (30) to be
setup.
3. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.12 BDRECL - Specify new Record Length for Disc I/O
This subprogram specifies a new record length for all
subsequent BDSAVE operations.
Calling Sequence
STATUS = BDRECL(JW,RECLEN)
Input Parameters
JW YBOS array
RECLEN (Integer) RECORD length...longwords
Output Parameters
None
Function Value
BDRECL (Integer) YESUCC Success
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. A RECLEN of -1 will cause the default (128 longwords)
to be setup.
3. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.13 BDLIST - Modify A Bank Set With All Banks On Disk
This subprogram modifies the input bank set by adding all
bank names on disk to it, dropping all bank names on disk from
it, or defining it as all bank names on disk.
Calling Sequence
STATUS = BDLIST(JW,LUNIT,OPT)
Input Parameters
JW YBOS array
LUNIT (Integer) The logical unit of the opened file
OPT (Character*2) Option specifier
Output Parameters
None
Function Value
BDLIST (Integer) Status Flag
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The logical unit, LUNIT, must have been opened by a
previous BDOPEN call.
3. The option specifier is a string of two characters of
the form 'L=', 'L+' or 'L-' where L is one of the
allowed bank set names (A-Z) and '=' means copy, '+'
means add and '-' means delete.
4. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.14 BDNEAR - Find The First Bank Number On Disk That
Exceeds A Threshold
This subprogram finds the first bank of a given name
whose number exceeds some input threshold number.
Calling Sequence
STATUS = BDNEAR(JW,LUNIT,NAME,NR,NRNXT)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical unit of open file
NAME (Character*4) Bank Name
NR (Integer) Threshold bank number
Output Parameters
NRNXT (Integer) Number of first existing bank with name NAME
such that NRNXT>NR
Function Value
BDNEAR (Integer) Status Flag
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The logical unit, LUNIT, must have been opened by a
previous BDOPEN call.
3. The bank with name NAME and number NR need not exist
on disk.
4. This search operation requires no disk I/O.
5. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.15 BDNLST - Return A List Of All Banks On Disk With A
Given Name
This subprogram returns the index of a work bank that
holds a list of all banks on disk with the input name.
Calling Sequence
STATUS = BDNLST(JW,LUNIT,NAME,INDX)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical unit of open file
NAME (Character*4) Bank Name
Output Parameters
INDX (Integer) Index to the list work bank
Function Value
BDNLST (Integer) Status Flag
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The logical unit, LUNIT, must have been opened by a
previous BDOPEN call.
3. This search operation requires no disk I/O.
4. The numbers of all banks on disk of name NAME are
sequentially stored in JW(INDX+1) to
JW(INDX+JW(INDX)).
5. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.16 BDBGST - Find Largest Bank Number On Disk For A Given
Name
This subprogram returns the largest bank number on disk
for the input name.
Calling Sequence
STATUS = BDBGST(JW,LUNIT,NAME,NR)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical unit of opened file
NAME (Character*4) Bank Name
Output Parameters
NR (Integer) Largest bank number on disk for
name NAME
Function Value
BDBGST (Integer) Status Flag
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The logical unit, LUNIT, must have been opened by a
previous BDOPEN call.
3. This search operation requires no disk I/O.
4. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.17 BDSMLL - Find Smallest Bank Number On Disk For A Given
Name
This subprogram returns the smallest bank number on disk
for the input name.
Calling Sequence
STATUS = BDSMLL(JW,LUNIT,NAME,NR)
Input Parameters
JW YBOS array
LUNIT (Integer) Logical unit of opened file
NAME (Character*4) Bank Name
Output Parameters
NR (Integer) Smallest bank number on disk for
name NAME
Function Value
BDSMLL (Integer) Status Flag
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The logical unit, LUNIT, must have been opened by a
previous BDOPEN call.
3. This search operation requires no disk I/O.
4. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.18 BDJRNL - Turn On/off File Journaling
This subprogram enables/disables file journaling for the
files opened by BDOPEN calls that follow. File journaling is
relevant only for files opened for write access.
Calling Sequence
STATUS = BDJRNL(JW,MODE)
Input Parameters
JW YBOS array
MODE (Integer) Journal Mode:
MODE = 1 Journaling enabled
MODE = 0 Journaling disabled
Output Parameters
NONE
Function Value
BDJRNL (Integer) Status Flag
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. YBOS file Journaling protects against corruption of
files due to improper program termination.
3. File journaling means that BDOPEN will create a copy
of the file ,FILNAM, and open the copy for YBOS disk
I/O. BDCLOS will rename the copy (the journal file)
to FILNAM only after all I/O is complete. It is
important that BDCLOS be called to complete the I/O
session. Failure to call BDCLOS will result in the
journal file not being renamed, and important file
header data being lost. Thus, if BDCLOS is not
called, all I/O will be lost and file FILNAM will
remain as it was prior to the BDOPEN.
4. File journaling is, by default, enabled for files
opened for write access.
5. Since journaling involves additional overhead, YBOS
I/O performance is hindered. Thus, it is suggested
that journaling be disabled for less important files.
For example:
STATUS = BDJRNL(JW,0) (disable journaling)
STATUS = BDOPEN(JW,LUNIT,'DUMMY.DAT')
.
.
STATUS = BDJRNL(JW,1) (Enable journaling)
STATUS = BDOPEN(JW,LUNIT,'FILE1.DAT')
STATUS = BDOPEN(JW,LUNIT,'FILE2.DAT')
STATUS = BDOPEN(JW,LUNIT,'FILE3.DAT')....
6. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
21.19 BDSEAR - Search A Disk File For A Target Bank
This Subroutine is used to locate a bank (NAME, STRNUM)
in a binary search work bank (disk file dictionary), then
read, from disk, a bank of the same name that is OFFSET banks
from STRNUM.
Calling Sequence
STATUS = BDSEAR(JW,LUNIT,NAME,STRNUM,STROFF,OFFSET,INDWK)
Input Parameters
JW (Integer*4 Array) YBOS Array that the target bank is read
into.
LUNIT (Integer*4) I/O logical unit for the desired disk file
NAME (Character) Bank name
STRNUM (Integer*4) Start bank number
STROFF (Integer*4) Offset to start bank number in bin sear.
OFFSET (Integer*4) Offset from STRNUM to target bank
Output Parameters
INDWK (Integer*4) Index to a work bank holding
the target bank index and bin.
sear. offsets. This work bank index
is specific to a given bank name
and I/O channel. It is the users
reposibility to maintain its uniqueness.
Function Value
BDSEAR (Integer) Status Flag
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The disk file must have already been opened by
BDOPEN.
3. The index to target bank, and the offsets in the
binary search work bank to the target and start banks
are located in a work bank pointed to by INDWK. The
offsets in the INDWK work bank are used to avoid
binary searching for STRNUM in the case of second,
third... calls to BDSEAR (if STROFF is 0, a binary
search for STRNUM will result; if STROFF JW(INDWK+2)
or JW(INDWK+3), no binary search is needed).
JW(INDWK+1) = Target bank index
JW(INDWK+2) = offset to the start bank's entry in the Disk
file dictionary.
JW(INDWK+3) = offset to the target bank's entry in the Disk
file disctionary.
example!!!!!!
next page