HP 3000 Manuals HP 3000 Manuals
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 base item 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 (note that 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 (note that 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 (note that 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 (note that 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.
Mode 201: Set Number
Mode 201 defines the type of access available for a specific data set.
Qualifier identifies the data set name or number for which the
information is requested.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | +/- Data set number |
| | |
-----------------------------------------------------
If the data set number is positive, the user class has only
read access. If the number is negative, the user class has
both read and write access.
Mode 202: Set Name
Mode 202 describes a specific data set.
Qualifier identifies the data set name or number for which the
information is requested.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1-8 | Data set name |
| | |
-----------------------------------------------------
| | |
| 9 | One of the following set types |
| | followed by a blank: |
| | |
| | |
| | M, A, D |
| | |
-----------------------------------------------------
| | |
| 10 | Entry length |
| | |
-----------------------------------------------------
| | |
| 11 | Blocking factor |
| | |
-----------------------------------------------------
| | |
| 12 | 0 |
| | |
-----------------------------------------------------
| | |
| 13 | 0 |
| | |
-----------------------------------------------------
| | |
| 14-15 | Number of entries in set |
| | |
-----------------------------------------------------
| | |
| 16-17 | Capacity of set |
| | |
-----------------------------------------------------
The data set name is left-justified and will be padded with
blanks if the name is shorter than 16 characters.
Mode 203: Sets in Database
Mode 203 identifies all data sets available in a database and the type of
access allowed. If you are using third-party indexing, this mode does
not show third-party index files.
Qualifier is ignored.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | Set count x |
| | |
-----------------------------------------------------
| | |
| 2 | +/- Data set number 1 |
| | |
-----------------------------------------------------
| | |
| : | : |
| | |
-----------------------------------------------------
| | |
| n + 1 | +/- Data set number n |
| | |
-----------------------------------------------------
If the data set number is positive, the user class has only
read access to the data set and possibly is in the write class
list of specific data item(s). If the number is negative, the
user class has both read and write access. The data sets are
listed in data set number order.
Mode 204: Sets with Item
Mode 204 identifies all data sets available which contain a specified
data item and indicates the type of access allowed.
Qualifier identifies the data item name or number for which the
information is requested.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | Set count x |
| | |
-----------------------------------------------------
| | |
| 2 | +/- Data set number 1 |
| | |
-----------------------------------------------------
| | |
| : | : |
| | |
-----------------------------------------------------
| | |
| n + 1 | +/- Data set number n |
| | |
-----------------------------------------------------
If the data set number is positive, the user class has only
read access to the data set and possibly is in the write class
list of specific data item(s). If the number is negative, the
user class has both read and write access. The data sets are
listed in data set number order.
[REV BEG]
Mode 205: Set Capacity
Mode 205 is an extension of mode 202 with dynamic capacity expansion
information.
Qualifier identifies the data set name or number for which the
information is requested.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1-8 | Data set name |
| | |
-----------------------------------------------------
| | |
| 9 | One of the following set types |
| | followed by a blank: |
| | |
| | |
| | M, A, D |
| | |
-----------------------------------------------------
| | |
| 10 | Entry length |
| | |
-----------------------------------------------------
| | |
| 11 | Blocking factor |
| | |
-----------------------------------------------------
| | |
| 12 | 0 |
| | |
-----------------------------------------------------
| | |
| 13 | 0 |
| | |
-----------------------------------------------------
| | |
| 14-15 | Number of entries in set |
| | |
-----------------------------------------------------
| | |
| 16-17 | Capacity of set |
| | |
-----------------------------------------------------
| | |
| 18-19 | High-water mark |
| | |
-----------------------------------------------------
| | |
| 20-21 | Maximum capacity |
| | |
-----------------------------------------------------
| | |
| 22-23 | Initial capacity |
| | |
-----------------------------------------------------
| | |
| 24-25 | Incremental number of entries |
| | |
-----------------------------------------------------
| | |
| 26 | Incremental percent |
| | |
-----------------------------------------------------
| | |
| 27 | Dynamic capacity expansion flag |
| | (0 = off, 1 = on) |
| | |
-----------------------------------------------------
The data set name is left-justified and will be padded with
blanks if the name is shorter than 16 characters.
Mode 205 can be used for any master or detail data set with or
without dynamic capacity expansion capability.
Mode 205 allows users to obtain information on dynamic data
set capacity expansion programmatically. It is an extension
of mode 202 to include dynamic capacity expansion information
such as maximum capacity, initial capacity, incremental number
of entries, incremental percent, and the dynamic capacity
expansion flag (0 for off and 1 for on) for the data set.
[REV END]
Mode 301: Paths
Mode 301 identifies the paths defined for a specified data set.
Qualifier identifies the data set name or number for which the
information is requested.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | Path count x |
| | |
-----------------------------------------------------
| | |
| 2 | Data set number of path 1 |
| | |
-----------------------------------------------------
| | |
| 3 | Search item number of path 1 |
| | |
-----------------------------------------------------
| | |
| 4 | Sort item number of path 1 |
| | |
-----------------------------------------------------
| | |
| : | : |
| | |
-----------------------------------------------------
| | |
| 3n-1 | Data set number of path n |
| | |
-----------------------------------------------------
| | |
| 3n | Search item number of path n |
| | |
-----------------------------------------------------
| | |
| 3n+1 | Sort item number of path n |
| | |
-----------------------------------------------------
Elements 2 to 4 are repeated for each path.
If qualifier specifies a master data set, the set number
identifies the detail data set.
If qualifier specifies a detail data set, the set number
identifies the master data set.
If qualifier specifies a master data set, the item numbers
identify items in the detail data sets. If you do not have
access to a search item, it is not included in the path count
and the path information is not returned. If a sort item does
not exist or you do not have access to it, the sort item
number is zero.
Path designators are presented in the order in which they
appear in the schema.
Mode 302: Key or Search Item
Mode 302 identifies the key or search item for a specified data set. For
this mode the two qualifiers are shown separately.
Qualifier identifies the master data set name or number for which the
information is requested.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | Key item number |
| | |
-----------------------------------------------------
| | |
| 2 | 0 |
| | |
-----------------------------------------------------
If qualifier specifies a master data set, the key item number
is the number in the master set. The number is 0 if you do
not have access to the key item.
OR
Qualifier identifies the detail data set name or number for which the
information is requested.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | Search item number |
| | |
-----------------------------------------------------
| | |
| 2 | Master data set number |
| | |
-----------------------------------------------------
If qualifier specifies a detail data set, the primary search
item and the related master data set number are returned.
Both numbers are 0 if you do not have access to the search
item.
Mode 401: Logging
Mode 401 obtains information related to logging.
Qualifier is ignored.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1-4 | Log identifier name |
| | |
-----------------------------------------------------
| | |
| 5 | Database log flag |
| | |
-----------------------------------------------------
| | |
| 6 | User log flag |
| | |
-----------------------------------------------------
| | |
| 7 | Transaction flag |
| | |
-----------------------------------------------------
| | |
| 8-9 | User transaction number |
| | |
-----------------------------------------------------
The log identifier name is left-justified and padded with
blanks if shorter than 8 characters.
If the database is enabled for logging, the database log flag
is 1; otherwise it is 0.
If you are logging, the user log flag is 1; otherwise it is 0.
If you have a transaction in progress, the transaction flag is
1; otherwise it is 0.
The user transaction number is one word.
Mode 402: ILR
Mode 402 returns information about Intrinsic Level Recovery (ILR).
Qualifier is ignored.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | ILR log flag |
| | |
-----------------------------------------------------
| | |
| 2 | Calendar date (mmddyy) |
| | |
-----------------------------------------------------
| | |
| 3-4 | Clock time (one word in format |
| | hhmmsstt) |
| | |
-----------------------------------------------------
| | |
| 5 | 0 |
| | |
-----------------------------------------------------
| | |
| 6-14 | _ |
| | |
-----------------------------------------------------
| | |
| 15-16 | Reserved |
| | |
-----------------------------------------------------
If the database is enabled for ILR, the ILR log flag is 1;
otherwise it is 0.
The calendar date is the date ILR was enabled.
The clock time is the time ILR was enabled.
Element 5 is always 0.
_ indicates blank. Elements 6 to 14 are always blank.
Elements 15 and 16 are reserved.
Mode 403: Dynamic Roll-Back
Mode 403 obtains information related to dynamic transaction activity on a
given database.
Qualifier is ignored.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1-4 | Log identifier name |
| | |
-----------------------------------------------------
| | |
| 5 | Database log flag |
| | |
-----------------------------------------------------
| | |
| 6 | User log flag |
| | |
-----------------------------------------------------
| | |
| 7 | Logical transaction flag |
| | |
-----------------------------------------------------
| | |
| 8-9 | User transaction number |
| | |
-----------------------------------------------------
| | |
| 10-11 | XM log set size (in megabytes) |
| | |
-----------------------------------------------------
| | |
| 12 | XM log set type |
| | |
-----------------------------------------------------
| | |
| 13 | Database attached flag |
| | |
-----------------------------------------------------
| | |
| 14 | Dynamic transaction flag |
| | |
-----------------------------------------------------
| | |
| 15-26 | XM log set name |
| | |
-----------------------------------------------------
The log identifier name is left-justified and padded with
blanks if shorter than 8 characters.
If the database is enabled for logging, the database log flag
is 1; otherwise it is 0.
If you are logging, the user log flag is 1; otherwise it is 0.
If no logical transaction is in progress, the transaction flag
is 0. If a static transaction is in progress, the flag is set
to 1; if a multiple database transaction is in progress, the
flag is set to 2.
The user transaction number is one word.
The Transaction Management (XM) log set is measured in
megabytes.
If the XM log set is circular, the log set type is CR;
otherwise it is LN indicating a linear log.
If the database is attached to XM, the database attached flag
is 1; otherwise it is 0.
If the user is processing a dynamic transaction, the dynamic
transaction flag is 1; otherwise it is 0.
If the database is associated with the default XM user log
set, the XM log set name element contains blanks; otherwise it
contains the name of the XM log set.
Mode 404: Logging Subsystem Information
Mode 404 returns information about multiple database transactions.
Qualifier is ignored.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | Database log flag |
| | |
-----------------------------------------------------
| | |
| 2 | User log flag |
| | |
-----------------------------------------------------
| | |
| 3 | Roll-back log flag |
| | |
-----------------------------------------------------
| | |
| 4 | ILR log flag |
| | |
-----------------------------------------------------
| | |
| 5 | MUSTRECOVER flag |
| | |
-----------------------------------------------------
| | |
| 6 | Database remote flag |
| | |
-----------------------------------------------------
| | |
| 7 | Logical transaction flag |
| | |
-----------------------------------------------------
| | |
| 8-11 | Log identifier name |
| | |
-----------------------------------------------------
| | |
| 12-13 | Log index |
| | |
-----------------------------------------------------
| | |
| 14-15 | Multiple database transaction ID |
| | |
-----------------------------------------------------
| | |
| 16 | Number of databases involved in |
| | the multiple database transaction |
| | |
-----------------------------------------------------
| | |
| 17-31 | Base IDs of the databases involved |
| | in the multiple database |
| | transaction |
| | |
-----------------------------------------------------
If the database is enabled for logging, the database log flag
is 1; otherwise it is 0.
If you are logging, the user log flag is set to 1; otherwise
it is 0. If a user accesses the database with a DBOPEN mode
5, this flag is set to 0.
If the database is enabled for roll-back logging, the
roll-back log flag is set to 1; otherwise it is 0.
If the database is enabled for ILR, the ILR log flag is set to
1; otherwise it is 0.
If the database is enabled for MUSTRECOVER, the MUSTRECOVER
flag is set to 1; otherwise it is 0.
If the database resides on a remote system, the database
remote flag is set to 1. If the database resides on the local
system, the flag is set to 0.
If no logical transaction is in progress, the transaction flag
is set to 0. If a static transaction is in progress, the flag
is set to 1. If a multiple database transaction is in
progress, the flag is set to 2.
The log index is used to call the WRITELOG intrinsic. It is
set to 0 if logging is not used.
The transaction ID represents a multiple or single database
transaction.
Elements 16-31 are set when a multiple database transaction is
in progress.
Mode 501: Subsystem Access
Mode 501 checks subsystem access to the database. Refer to the DBUTIL
>>SHOW and >>SET commands described in chapter 8 for more information.
Qualifier is ignored.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | Subsystem access |
| | |
-----------------------------------------------------
The following values are used for subsystem access:
0 No access
1 Read access
3 Read/write access
Mode 502: Critical Item Update
Mode 502 checks the critical item update (CIUPDATE) option settings for
the database and the current DBOPEN. The CIUPDATE option is set for the
database with the DBUTIL >>SET command and then, depending on the
setting, can be enabled or disabled with DBCONTROL for the current
DBOPEN. Refer to the discussion of DBCONTROL in this chapter and the
descriptions of the DBUTIL >>SHOW and >>SET commands in chapter 8 for
more information.
Qualifier is ignored.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | Critical item update flag |
| | |
-----------------------------------------------------
| | |
| 2 | Current setting for accessor |
| | |
-----------------------------------------------------
For element 1, the following values are used for the CIUPDATE
option setting specified with DBUTIL for the database:
0 Critical item update is disallowed (default).
1 Critical item update is allowed.
2 Critical item update is on.
For element 2, the following values are used for the current
DBOPEN setting specified with DBCONTROL:
0 Critical item update is disabled for this accessor.
1 Critical item update is enabled for this accessor.
Modes 8nn: Third-Party Indexing
Modes 8nn are used to return information related to third-party indexing
(TPI). If your database is enabled for TPI, refer to your vendor
documentation for additional DBINFO mode information. The section on
DBUTIL in chapter 8 of this book has a brief description of the TPI
option.
Mode 901: Language
Mode 901 obtains the Native Language attribute of the database. It
returns the MPE/iX code for the language attribute.
Qualifier is ignored.
Buffer returns the following (note that each element is a halfword or
two bytes):
-----------------------------------------------------
| | |
| Element | Contents |
| | |
-----------------------------------------------------
| | |
| 1 | Language ID |
| | |
-----------------------------------------------------