HP 3000 Manuals

TurboIMAGE/XL Database Management System Reference Manual

Reading the Data 

When you read data from the database, you specify which data set and
which entry in that data set you want.  If the user class number with
which you opened the database grants you read access, you can read the
entire entry or specific data items from the entry.  You specify the
items to be read and the array where the values should be stored.  You
can read items or entries in any access mode if your user class grants
read access to the data element.

To understand the various ways you can select the data entry to be read,
it is important to know a little about the data set structure.  Each data
set consists of one disk file and each data entry is a logical record in
that file.  Each entry is identified by the relative record number in
which it is stored.  The first record in the data set is record number 1
and the last is record number n, where n is the capacity of the data set.

At any given time, a record may or may not contain an entry.
TurboIMAGE/XL maintains internal information indicating which records of
a data set contain entries and which do not.

Current Path 

TurboIMAGE/XL maintains a current path for each detail data set and for
each database accessor (that is, each DBOPEN). The current path is
established by the DBFIND procedure, or if no call has been made to this
procedure, it is the primary path for the data set.  Each time an entry
is read, no matter what read method is used, TurboIMAGE/XL saves the
entry's backward and forward chain pointers for the current path.  For
more information about how the current path is used, refer to the
discussion of chained access later in this chapter.

If an entry is read from a master data set, the chain pointers are
synonym chain pointers and have no relationship to a path.

Reading Methods 

The methods for requesting a data entry are categorized as follows:

   *   Directed access
   *   Serial access
   *   Calculated access
   *   Chained access

All of these methods are available through the TurboIMAGE/XL library
procedure DBGET. The chained access method also requires the use of the
DBFIND procedure.  Figure 4-2  illustrates the access methods using
two data sets from the ORDERS database.


          Figure 4-2.  Reading Access Methods (DBGET Procedure) 

Directed Access.   

The directed access method of selecting the data entry to be read
requires that you specify the record number of that entry.  Record
numbers are returned in status halfwords 3-4 by a successful call to the
TurboIMAGE/XL intrinsic DBPUT (refer to the discussion of DBPUT in
chapter 5).  Other numbers that can be used for directed reads are the
forward and backward pointers returned in status halfwords 7-8 and 9-10.
To use these numbers for directed reads, you need to save them because
subsequent TurboIMAGE/XL procedure calls can overwrite the status area.

During directed access the calling program specifies a record number or
address.  If any entry exists at this address, TurboIMAGE/XL returns the
values for the data items requested in the calling program's buffer.  If
no such entry exists, the program is notified by an exceptional condition
return, such as end-of-file, beginning-of-file, or no entry.

This access method can be used with any type of data set and is useful in
situations where the calling program has already determined the record
number of the entry to be read.  For example, if a program surveys
several entries using another access method to determine which one it
wants to use in a report, it can save each record number and use the
record number of the entry it selects to read the entry again using the
directed access method.

If a program performs a directed read of record 3 of the INVENTORY data
set, the entry marked with a hollow arrow in Figure 4-2  is read.  If
a directed read of the SUP-MASTER data set record 7 is performed, the
entry in that set marked with the same type of arrow is read.


NOTE  When using this type of access with master data sets, you should be
      aware of migrating secondaries.  These are described in chapter 10.


Locking.  If concurrent users are allowed to add to or delete from a data
set, locking should be used during the search and report sequence to
ensure the record numbers do not change before they are used.  In this
type of application, a data set lock is usually the most appropriate.

Serial Access.   

In this mode of retrieval, TurboIMAGE/XL starts at the most recently
accessed storage location for the data set, called the current record,
and sequentially examines adjacent records until the next entry is
located.  Data items from this entry are returned to the calling program,
and its location becomes the current record.

You can use both forward and backward serial access.  Forward serial
access consists of retrieving the next greater-numbered entry, and
backward serial access consists of retrieving the previous lower-numbered
entry.  If no entry is located, TurboIMAGE/XL returns an end-of-file if
requested access is forward, or a beginning-of-file if it is backwards.

Because no current record exists the first time a program requests an
entry from a data set, a request for forward serial access causes
TurboIMAGE/XL to search from record 1.  Similarly, a backward serial
retrieval begins at the highest numbered record.

The entries connected by curved arrows in Figure 4-2  are read by a
program using the serial access method.  If a forward serial read is
performed on the INVENTORY data set before any other type of read, the
entry in record number 2 is read.  If another forward serial read is
performed on the same data set, the entry in record 3 is read.  On the
other hand, if a serial read is performed and the current record is 6,
the entry in record 9 is read.  The next forward serial read returns an
end-of-file.

The serial access method can be used with any type of data set and is
very useful if most or all of the data in the data set is to be
retrieved, for example, to be used in a report.  It is efficient to
retrieve all the data in a serial manner, copy it to a file, and sort it
with routines external to TurboIMAGE/XL before printing the report.  The
availability of serial access effectively allows you to use a data set in
the same way you would use an MPE/iX file.  Thus, you have the advantages
of TurboIMAGE/XL database organization and the efficiency of serial
access.

Locking.  If concurrent users are allowed to modify the data set (access
mode 1), you may wish to lock the data set or database before you begin
the serial access sequence.  Locking prevents entries from being added,
modified, moved, or removed by the other processes.

Calculated Access.   

The calculated access method allows you to retrieve an entry from a
master data set by specifying a particular key item value.  For example,
the SUP-MASTER data entry for the supplier Acme shown in Figure 4-2 ,
can be retrieved with this method because SUPPLIER is a key item in the
SUP-MASTER data set.  TurboIMAGE/XL locates the entry in the data set
whose key item value matches the requested value.  The exact technique
used to perform calculated access is described in chapter 10.

Calculated access can be used only with master data sets.  It is very
useful for retrieving a single entry for some special purpose.  For
example, a program used infrequently to get information about a
particular customer or supplier could use calculated access to quickly
locate the information in the ORDERS database.

Chained Access.   

The chained access method is used to retrieve the next entry in the
current chain.  To perform chained access of detail data set entries, you
must first locate the beginning of the chain you want to retrieve, and
thus establish the current chain, by calling the DBFIND procedure.  The
calling program specifies the name of the detail search item that defines
the path to which the chain belongs and a value for the item.
TurboIMAGE/XL determines which master set forms a path with the specified
search item and locates the entry in that master data set whose key item
value matches the specified value.  The entry it locates contains
pointers to the first and last entries in the desired chain and a count
of the number of entries in the chain.  This information is maintained
internally and defines the attributes of the current path.

If a program uses chained access to read the INVENTORY data set entries
pertaining to the supplier H&S SURPLUS shown in Figure 4-2 , it must
first call the DBFIND procedure to locate the chain head in the
SUP-MASTER data set.  The program specifies the INVENTORY data set, the
SUPPLIER search item in the INVENTORY data set, and the value H&S SURPLUS
for that item.  TurboIMAGE/XL uses a calculated read to locate the
SUP-MASTER entry with a key item value of H&S SURPLUS. If the program
then requests a forward chained read using the DBGET procedure, the entry
in record 9 of INVENTORY, which is set at the beginning of the chain, is
read.  If a backward chained read is requested, the entry in record 5 is
read.

If the last call to DBGET used chained access to read the entry in record
9, the next forward chained read reads the entry in record 2 of the
INVENTORY data set.

Once a current path and chain have been established for a detail data
set, the calling program can use the chained access method of retrieving
data.  You can use both forward and backward chained access.  In either
case, if there are no more entries in the chain when you request the next
one, DBGET returns an exceptional condition, beginning-of-chain or
end-of-chain for backward and forward access, respectively.

Chained access to master data sets retrieves the next entry in the
current synonym chain.  The use of synonym chains applies to only a
limited number of special situations.  They are discussed in chapter 10.

Chained access to detail data sets is particularly useful when you want
to retrieve information about related events such as all inventory
records for the H&S Surplus supplier in the ORDERS database.

Locking.  If concurrent users are allowed to modify data entries in the
chain you are currently accessing, you can use locking to ensure data
consistency.  For example, suppose a chain consists of several data
entries, each containing a line item from a particular order.  If user A
is performing a series of chained reads while user B is canceling the
order by deleting data entries one by one, user A could retrieve an
incomplete order.  To prevent this from happening, a lock can be
established covering the group of data entries to be retrieved (the
chain, in this case).  This can usually be done with a single DBLOCK
call.  Refer to the discussion of the locking facility later in this
chapter.

Rereading the Current Record 

The DBGET library procedure allows you to read the entry from the most
recently accessed record again.  You may want to do this in a program
that has unlocked the data entry and locked it again and needs to check
if the contents of the current entry have been changed.

Note that if a DBFIND procedure call has been made, the current record is
zero and a request to reread the entry causes DBGET to return an
exceptional condition indicating that the current record contains no
entry.  Refer to table 5-13 for more information on DBGET return status
values.

MPE/iX 5.0 Documentation