HP 3000 Manuals HP 3000 Manuals
Using TurboIMAGE/XL Intrinsics (Cont.)
DBGET
INTRINSIC NUMBER 405.
Provides eight different methods for accessing the entries of a data set.
Syntax.
DBGET,base,dset,mode,status,list,buffer,argument
Parameters.
base is the name of the array used as the base parameter
when opening the database. The first element of
the array must contain the base ID returned by
DBOPEN. (Refer to DBOPEN for more information about
base ID.)
dset is the name of an array containing the
left-justified name of the data set to be read, or
is an integer referencing the data set by number.
The data set name can be up to 16 characters long.
If shorter, it must be terminated by a semicolon or
a blank.
mode contains an integer between 1 and 8, inclusive,
which indicates the reading method. The methods
are:
Mode Method
1 Re-read. Read the entry at the
internally maintained current record
number (argument parameter is ignored).
2 Serial Read. Read the first entry whose
record number is greater than the
internally maintained current number
(argument parameter is ignored).
3 Backward Serial Read. Read the first
entry whose record number is less than
the internally maintained current number
(argument parameter is ignored).
4 Directed Read. Read the entry, if it
exists, at the record number specified
in the argument parameter (argument is
treated as a 32-bit record number).[REV
BEG]
5 Chained Read or Next Qualified Entry
Read. Read the next entry in the
current chain, or read the next
qualified entry for a B-Tree DBFIND.
This is the entry referenced by the
internally maintained forward pointer
(argument parameter is ignored).
Super-chains are traversed for detail
data sets.[REV END]
If your database is enabled for
third-party indexing (TPI), refer to
your vendor documentation for additional
information.
6 Backward Chained Read.
[REV BEG]
Read the previous entry in the current
chain, or the previous qualified entry
for a B-Tree DBFIND. This is the entry
referenced by the internally maintained
backward pointer (argument parameter is
ignored). Super-chains are traversed
for detail data sets.[REV END]
If your database is enabled for
third-party indexing (TPI), refer to
your vendor documentation for additional
information.
7 Calculated Read. (Master data sets
only.) Read the entry with a key item
value that matches the value specified
in argument. The entry is in the master
data set specified by dset.
8 Primary Calculated Read. (Master data
sets only.) Read the entry occupying
the primary address of a synonym chain
using the key item value specified in
argument to locate the entry. The key
item value returned is always that of
the primary entry and might not match
the value specified in argument. (Refer
to chapter 10 for synonym chain
description.)
If your database is enabled for third-party
indexing (TPI), refer to your vendor documentation
for additional DBGET modes. The section on DBUTIL
in chapter 8 of this book has a brief description
of the TPI option.
status is the name of a 10-halfword array in which
TurboIMAGE/XL returns status information about the
procedure. If the procedure executes successfully,
the status array contents are:
Element Contents
1 If the procedure succeeds, the return
status is 0. Table 5-13 describes
the contents of element 1 when the
procedure does not succeed.
2 Length of the logical entry read into
the buffer array in halfwords.
3-4 Word record number of the data entry
read.
5-6 Word zero, unless the entry read is a
primary entry in which case it is the
number of entries in the synonym
chain.[REV BEG]
7-8 Word record number of the preceding
entry in the chain of the current path
for the detail data sets. Zeroes for
master data sets.
9-10 Word record number of the next entry in
the chain of the current path for the
detail data sets. Zeroes for master
data sets.[REV END]
list is the name of an array containing an ordered set
of data item identifiers, either names or numbers.
The values for these data items are placed in the
array specified by the buffer parameter in the same
order as they appear in the list array.
The list array can contain a left-justified set of
data item names, separated by commas and terminated
by a semicolon or blank. No embedded blanks are
allowed and no name can appear more than once.
When referencing by number, the first element of
the list array is an integer n which is followed by
n unique data item numbers (one-halfword positive
integers).
The list not only specifies the data items to be
retrieved immediately but is saved internally by
TurboIMAGE/XL as the current list for this data
set. The current list is unchanged until a
different list is specified in a subsequent call to
DBGET, DBPUT, or DBUPDATE for the same access path
and data set.
Some special list constructs are allowed. These
are described in Table 5-20 with the DBPUT
procedure. List processing is a relatively high
overhead operation which can be shortened in
subsequent calls by using the asterisk construct to
specify that the current list is to be used. Use
of this construct can save considerable processing
time. However, be sure a current list exists
before using the asterisk or TurboIMAGE/XL will
assume a null list. If a DBCLOSE mode 2 is used
after DBGET, using the asterisk construct,
TurboIMAGE/XL uses the previously defined item
list.
buffer is the name of the array to which the values of
data items specified in the list array are moved.
The values are placed in the same order as
specified in the list array. The number of
elements occupied by each value corresponds to the
number required for each data type multiplied by
the sub-item count.
argument is ignored except when mode equals 4, 7, or 8.
If mode is 4, argument contains a word record
number of the entry to be read.
If mode is 7 or 8, argument contains a key item
value for the master data set referenced by dset.
Discussion.
The internal backward and forward pointers for the data set are replaced
by the current path's chain pointers from the entry just read.[REV BEG]
If the data set is a master, and not a B-Tree index, they are synonym
chain pointers (refer to chapter 10).[REV END] If it is a detail with at
least one path, the current path is the one established by the last
successful call to DBFIND; or, if no call has been made, it is the
primary path. If there are no paths defined, the internal pointers are
set to zeros.
The location of the entry just read becomes the current record for the
data set. DBGET mode 5 or 6 will reread the current record and will try
to continue the chain read if it encounters a broken chain.
[REV BEG]
NOTE A call to DBOPEN does not open individual data sets. Thus, a call
to DBGET (or DBFIND) that accesses a data set for the first time
(or after the data set has been closed), must open the data set as
well as jumbo files and B-Tree index files. This causes extra
overhead not incurred by subsequent calls to the same data set by
DBFIND or DBGET.
[REV END]
Table 5-13. DBGET Return Status Values
-----------------------------------------------------------------------------------------------
| | | |
| File System, Memory | -1 | FOPEN failure. |
| Management, and | -3 | FREADDIR failure. |
| Transaction Management | -4 | FREADLABEL failure. |
| Failures: | -168 | Cannot attach n to MPE XL XM: file system error nn. |
| | -169 | Invalid mode for XM attach options. |
| | -175 | Cannot attach n to MPE XL XM: XM error nn. |
| | -176 | Cannot detach n from MPE XL XM: XM error nn. |
| | -178 | Cannot detach n from MPE XL XM: file system error |
| | -209 | nn. |
| | | Invalid mode for XM detach options. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Calling Errors: | -11 | Bad database reference. |
| | -21 | Bad data set reference. |
| | -31 | Bad mode. |
| | -51 | Bad list length. |
| | -52 | Bad list or bad item. |
| | -222 | Only DBXUNDO allowed when a dynamic transaction |
| | | encounters an error. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Communications Errors: | -102 | DSWRITE failure. |
| | -106 | Remote 3000 data inconsistent. |
| | -107 | NS 3000 or DS 3000 system error. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Exceptional Conditions: | | DBGET Modes |
| | 10 | Beginning of file. (3) |
| | 11 | End of file. (2) |
| | 12 | Directed beginning of file. (4) |
| | 13 | Directed end of file. (4) |
| | 14 | Beginning of chain/qualifier (6) |
| | 15 | entries. (5) |
| | 17 | End of chain/qualifier entries. (1,4,7,8) |
| | 18 | No entry. (5,6) |
| | 49 | Broken chain. |
| | 50 | Illegal buffer address. |
| | | Buffer is too small (will only be |
| | | returned if buffer is too small |
| | | and the data transfer would write |
| | 62 | over stack markers in the user's |
| | 63 | stack). |
| | | DBG full. |
| | -193 | DBG disabled; potential damage; |
| | -3nn | only DBCLOSE allowed. |
| | -332 | DBU control block is full. |
| | -333 | Internal error. |
| | | Error in QLOCK table operation. |
| | | Error in QOPEN table operation. |
| | | |
-----------------------------------------------------------------------------------------------
Consult appendix A for more information about these conditions.
DBINFO
INTRINSIC NUMBER 402.
Provides information about the database being accessed. The information
returned is restricted by the user class number established when the
database is opened; any data items, data sets, or paths of the database
which are inaccessible to that user class are considered to be
non-existent.
Syntax.
DBINFO,base,qualifier,mode,status,buffer
Parameters.
base is the array name used as the base parameter when
opening the database; must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for additional
base ID information.)
qualifier is the name of an array containing a data set/data
item name or an integer referencing a data
item/data set, depending on the value of the mode
parameter (refer to "Discussion" for mode/qualifier
relationship). This parameter form is identical to
the dset and item parameters for DBFIND, and the
dset and list parameters for DBPUT.
mode is an integer indicating the type of information
desired. Refer to "Discussion" for mode integer
information (data item modes 1nn; data set modes
2nn; path modes 3nn; logging, dynamic roll-back
recovery, and multiple database transaction modes
4nn; subsystem and critical item update modes 5nn;
third-party indexing modes 8nn; and language modes
9nn.)
status is the name of an array of 10 halfwords in which
TurboIMAGE/XL returns status information about the
procedure. If the procedure executes successfully,
the status array contents are:
Element Contents
1 If the procedure succeeds, the return
status is 0. Table 5-14 describes
the contents of element 1 when the
procedure does not succeed.
2 Length of information in buffer array
(in halfwords).
3-4 Unchanged from previous procedure call
using this array.
5-10 Information about the procedure call and
its results. Refer to "Library
Procedure Error Messages" in appendix A
for a description of this information.
buffer is the name of an array in which the requested
information is returned. The contents of the
buffer array vary according to the mode parameter
used. They are also described in "Discussion" on
the following pages.
Table 5-14. DBINFO Return Status Values
----------------------------------------------------------------------------------------------
| | | |
| File System, Memory | -1 | FOPEN failure. |
| Management, and | -4 | FREADLABEL failure. |
| Transaction Management | -168 | Cannot attach n to MPE XL XM: file system error nn. |
| Failures: | -169 | Invalid mode for XM attach options. |
| | -175 | Cannot attach n to MPE XL XM: XM error nn. |
| | -176 | Cannot detach n from MPE XL XM: XM error nn. |
| | -178 | Cannot detach n from MPE XL XM: file system error |
| | -209 | nn. |
| | | Invalid mode for XM detach options. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Calling Errors: | -11 | Bad database reference. |
| | -21 | Bad data set reference. |
| | -31 | Bad mode. |
| | -222 | Only DBXUNDO allowed when a dynamic transaction |
| | | encounters an error. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Communications Errors: | -102 | DSWRITE failure. |
| | -106 | Remote 3000 data inconsistent. |
| | -107 | NS 3000 or DS 3000 system error. |
| | -206 | Remote TurboIMAGE/XL database exceeds IMAGE/3000 |
| | | limits. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Exceptional Conditions: | 49 | Illegal buffer address. |
| | 50 | Buffer too small for requested data. |
| | 63 | DBG disabled; potential damage; only DBCLOSE |
| | | allowed. |
| | | |
----------------------------------------------------------------------------------------------
Consult appendix A for more information about these conditions.
Discussion.
This section provides mode integer information for the following modes
(note that the mode/qualifier relationship is provided):
1nn - Data item modes
2nn - Data set modes
3nn - Path modes
4nn - Logging, dynamic roll-back recovery, and multiple database
transaction modes
5nn - Subsystem and critical item update modes
8nn - Third-party indexing modes
9nn - Language modes
Mode 101: Item Number.
Mode 101 defines the type of access available for a specific item.
Qualifier identifies the data item name or number for which the
information is requested.
Buffer returns the following (each element is a halfword or two
bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | +/- Data item number |
| | |
-----------------------------------------------------
If the data item number is positive, the user class has only
read access to the data item. If the number is negative, the
data item can be updated or the entry containing it can be
added or deleted in at least one data set.
Mode 102: Item Name.
Mode 102 describes a specific data item.
Qualifier identifies the data item name or number for which the
information is requested.
Buffer returns the following (each element is a halfword or two
bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1-8 | Data item name |
| | |
-----------------------------------------------------
| | |
| 9 | One of the following data types |
| | followed by a blank: |
| | |
| | |
| | I, J, K, R, U, X, Z, P |
| | |
-----------------------------------------------------
| | |
| 10 | Sub-item length |
| | |
-----------------------------------------------------
| | |
| 11 | Sub-item count |
| | |
-----------------------------------------------------
| | |
| 12 | 0 |
| | |
-----------------------------------------------------
| | |
| 13 | 0 |
| | |
-----------------------------------------------------
The data item name is left-justified and will be padded with
blanks if the name is shorter than 16 characters.
Mode 103: Items in Database.
Mode 103 identifies data items available in the database and displays the
type of access allowed. This mode does not identify unreferenced data
items, that is, those items that are defined in the item section of the
schema but are not referenced by at least one data set.
Qualifier is ignored.
Buffer returns the following (each element is a halfword or two
bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | Item count x |
| | |
-----------------------------------------------------
| | |
| 2 | +/- Data item number 1 |
| | |
-----------------------------------------------------
| | |
| : | : |
| | |
-----------------------------------------------------
| | |
| n + 1 | +/- Data item number n |
| | |
-----------------------------------------------------
If the data item number is positive, the user class has only
read access to the data item. If the number is negative, the
user class has both read and write access to the given data
set. The data items are listed in data item number order.
Mode 104: Items in Data Set.
Mode 104 identifies data items available in a specific data set and the
type of access allowed.
Qualifier identifies the data set name or number for which the
information is requested.
Buffer returns the following (each element is a halfword or two
bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | Item count x |
| | |
-----------------------------------------------------
| | |
| 2 | +/- Data item number 1 |
| | |
-----------------------------------------------------
| | |
| : | : |
| | |
-----------------------------------------------------
| | |
| n + 1 | +/- Data item number n |
| | |
-----------------------------------------------------
If the data item number is positive, the user class has only
read access to the data item. If the number is negative, the
user class has both read and write access in the given data
set. The data items are listed in order of occurrence in data
entry.
[REV BEG]