DBDRIVE 2020-10-12
Additional HELP topics are:
Calls, Commands, ModeNames, OpenModes, Overview
----------------------------------------------------------------
Overview:
DBDRIVE allows you to "drive around" in an IMAGE database, by
calling various IMAGE intrinsics. It is entirely different from
HP's DBDRIVER program.
DBDRIVE has about 20 variables, accessible by name (e.g.:
ARGUMENT). These variables can be examined (SHOW) and modified
(SET). Values can be entered as decimal numbers (123), hex
($7b), octal (%173), ascii (foo, or "foo fum"), or a combination
thereof.
There are two basic kinds of commands: IMAGE intrinsic calls,
and everything else.
The TurboIMAGE intrinsics are available as commands, where the
"DB" may be omitted from the command name (e.g., you could use
OPEN or DBOPEN to open a database).
DBDRIVE is available in NM or CM versions.
For a list of commands, do: HELP COMMANDS
Sample usage:
:run dbdrive
base sales
mode 1
open
list set 2
set qual 1
dbinfo 209 <- calls DBINFO 209 for set 1
exit
At startup, DBDRIVE initializes some flags from the PARM value:
Flag PARM bit PARM=
-------- -------- -------------------
TIMES 15 1
ACKALL 14 2
LISTHEX 13 4
DEBUG3 3 4096
DEBUG2 2 8192
DEBUG1 1 16384
---------------------------------------------------------------
Commands:
General commands:
?, //, BAse, BREAK, BTFIND, CSTs, DEBUG, EDIT, EXIT,
FORGET, FOrm, Help, HP32215, LIst, MODE, MONOFF, MONON,
NAME, NUMber, OFFSET, OPENCLOSE, PRIVTEST, REWind,
SETarray, SHowarray, STUFFBTI, UPDATEALL, USEq, VERsions,
What, CLEARREDO, DO, LISTREDO, REDO
Commands to call TurboIMAGE intrinsics:
BEGIN, CALL, CLOSE, CONTROL, DELETEq, END, ERRor, EXPlain,
FIND, GET, INFo, LOCK, MAINT, MEMO, OPEN, PUTq, STATus,
UNLOCK, UPDATE, XBEGIN, XEND, XUNDO
** All of the above commands may be prefixed with "DB", if
you like to type extra characters.
** Most intrinsic calling commands may be followed by:
MODE [=] <mode# | modename>
(e.g.: MODE 5)
which will temporarily set mode to the specified
value (without changing DBDRIVE's MODE variable).
Commands may be abbreviated to just the uppercase portion.
In the case of GET, if the mode is "directed mode" (5), then
the value of ARG will be incremented after each call to dbget.
In the case of DELETE, the second 32-bit word in STATUS will be
incremented after each call to dbdelete.
REPEAT ...
Some commands may be prefaced with an optional "REPEAT #"
phrase, which will cause them to be executed the specified
number of times. These commands are:
DELETE, GET, PUT
Commands, in alphabetic order:
//
Terminates DBDRIVE
BAse [basename [openmode]]
Specifies name of database to be opened (does not do the
open), and optionally sets the value of the MODE variable.
For a list of valid open modes, do: HELP OPENMODE
BEGIN [mode]
Calls DBBEGIN:
dbbegin (baseid, text, mode, status, text'len)
BREAK [PATH # / SYNonym] [FREE / INUSE]
[RECord #] [TURBO/NOTURBO]
[BACKp #] [NEXTp #] [COUnt #]
BREAK is used to deliberately inject an error into the
structure of the database.
The options may be in any order, some may be omitted. PATH
defaults to 1.
If this routine must do a DBGET to fetch the entry, then
FREE/INUSE defaults to the IMAGE flag, otherwise it defaults
to INUSE.
BTFIND [mode] relop value1
BTFIND [node] "[" value1, value2 "]"
CALL
Calls DBCALL, displays resulting text:
dbcall (status, outbuf, bytes)
CLOSE [mode]
Calls DBCLOSE:
dbclose (baseid, setname, mode, status)
CONTROL [mode]
Calls DBCONTROL:
dbcontrol (baseid, qualifier, mode, status)
CSTs
Shows procedure plabels and/or CST entries for IMAGE
intrinsics.
DEBUG
Calls the DEBUG intrinsic (requires SM capability)
DELETE[Q] [mode] [options] [may prefix with: REPeat #]
options ::= [SET #]
[RECord # [< /# | FOR #>] ]
[QUIET] [IGNERR]
Calls DBDELETE:
dbdelete (baseid, setname, mode, status)
EDIT variable
<variable> ::= <
ARGument | BACKPTR | BASEID | BASENAME | BTARG | BUFfer |
COUNT | DEBUGging | INFObuf | ITEM | LIST | MODE | NEXTPTR
OUTbuf | PASSword | PATHS | QUALifier | RECnum | RECORDS
SETNAME | STATus | TEXT | UVAR1 | UVAR2 >
EDIT calls qzmodify to edit the value of the specified
variable. When in qzmodify, you can get editing help by
typing control-W, and then an H.
See also: HELP SHOW for a list of variable and types.
END [mode]
Calls DBEND:
dbend (baseid, text, mode, status, text'len)
ERRor
Calls DBERROR:
dberror (status, outbuf, bytes)
EXIT
Terminates DBDRIVE
EXPlain [mode]
Calls DBEXPLAIN:
dbexplain (status)
FIND [mode]
Calls DBFIND:
dbfind (baseid, setname, mode, status, item, arg)
FORGET
FORGET simply forgets that you have opened a database, but
without actually closing it.
FOrm <ALL [@] | ITEMS [prefix] | PATHS | SET setname | SETS [@]>
FORM ALL does an implicit: FORM ITEMS, FORM SETS [@], FORM
PATHS.
FORM ITEMS reports information about every item in a database.
If a prefix is specified, only those items that start with the
prefix will be reported. Example: FORM ITEMS CUST
FORM PATHS reports information about paths between sets.
FORM SET <setname> reports information about the specified
set.
FORM SETS Reports information about every set in a database.
If the optional "@" is specified, an implied "FORM SET
<setname>" is done for every set.
GET [mode] [entry#] [READALL] [QUIET]
[may prefix with: REPeat #]
Calls DBGET:
dbget (baseid, setname, mode, status, list, buffer, arg)
DBGET is called with the current setname, list, & argument.
The results are displayed. If modename and record# are both
omitted, the current mode is used.
If a record# is given, mode is switched to DIRECTED.
For a list of valid modenames, do: HELP MODENAME
READALL means: repeat until a non-0 status is returned.
(For DIRECTED, the value of ARG is incremented after each
call)
Help [prefix]
If a prefix is specified, lists help information for all
topics or commands that match the prefix. (E.g., help C)
If prefix is omitted, displays the entire help file.
Help is fetched from a file (DBDRIVE.HELP.?) if possible,
otherwise from in-line text.
HP32215 #
Calls hp32215 () with the specified mode value. Modes:
0 routine name: 'HP32215'
AND* print copyright!
1 image version+: 'HP32215C.07.25 TurboIMAGE/XL '
2 image version: 'C.0725' (6 chars)
-1 reference man version:
'Edition 6 June 1997 30391C.07.03 (C) COPYRIG'
INFo [mode] [ <SET | ITEM> [ # | ALL ] ]
INFO ITEM calls DBINFO (..., item, ...)
INFO SET calls DBINFO (..., setname, ...)
INFO calls DBINFO (..., qualifier, ...)
INFO 205 SET ALL calls DBINFO (mode 205) for all sets
LIst [SET setname] [MODE <modename | #>]
[FOR #] [START #] [option]
[RECORD #] [TEXTonly] [RAW]
Lists all (or part) of a dataset.
For a list of valid modenames, do: HELP MODENAME
Valid options are:
EMPTY ---> show empty records too (at least,
indicate that they were encountered)
NAMes ---> lists pointers as entry names (default)
(IMAGE's internal format)
NUMbers ---> lists pointers as entry numbers
(usable in QUERY or DBDRIVE)
QUIET ---> suppresses list of contents of each record.
(mostly used to verify entire set can
be fetched successfully)
TEXTonly ---> don't do hex/octal dump of data, just show
the ASCII text ("." for non-printables)
RAW ---> dump entire record in hex
Note: the EMPTY, NAMes and NUMbers options are applicable only
when the database has been opened in mode -1.
LOCK [mode]
Calls DBLOCK:
dblock (baseid, qualifier, mode, status)
MAINT [mode]
Calls DBMAINT:
dbmaint (baseid, qualifier, mode, status)
MEMO [mode]
Calls DBMEMO:
dbmemo (baseid, text, mode, status, text'len)
MODE [value]
Displays (or sets) the value of MODE.
MONOFF
Turns off copying output to printer.
MONON
Turns on copying output to printer.
NAME # [BF #] [LIMIT #]
NAME converts an IMAGE entry name into an entry number.
If a blockfactor (BF #) is not specified, then the block
factor for the currently open dataset is used. If a dataset
is not open, and no block factor is given, then NAME will
fail.
Example: NAME 23
Example: NAME 23 BF 4
NUMber # [BF #] [LIMIT #]
NUMBER converts an IMAGE entry number into an entry name.
If a blockfactor (BF #) is not specified, then the block
factor for the currently open dataset is used. If a dataset
is not open, and no block factor is given, then NUMBER will
fail.
Example: NUMBER 23
Example: NUMBER 23 BF 4
OFFSET Block #
OFFSET Entry #
Calculates the block number for an entry, or
the entry number for the first entry in a block.
(The lowest entry number is 1.)
OPEN [basename [openmode]] [may prefix with: REPeat #]
Calls DBOPEN:
dbopen (baseid, password, mode, status)
OPEN will use the current MODE setting, which is initially
-1 at the start of DBDRIVE.
(Basename may be specified earlier via the BASE command.)
For a list of valid open modes, do: HELP OPENMODE
OPENCLOSE [may prefix with: REPeat #]
DBOPEN's a database, and then DBCLOSEs it.
PRIVTEST
(Requires open DB with set 1 being detail or something)
PUTq [mode] [may prefix with: REPeat #]
Calls DBPUT:
dbput (baseid, setname, mode, status, list, buffer)
REWIND
SET variablename value
SET [no]optionname
SETArray variablename value [value2 [value3...]]
SHOW <ALL | variablename> [variablename ...]
SHOW OPTIONS
SHOWArray variablename [variablename ...]
SET... sets the value of a variable.
SHOW... shows the value of one or more variables,
or shows all options
SETARRAY and SHOWARRAY treat the variables as if they were
variables of type "array".
variables and types... (booleans listed later)
ARGument array or buffer
BACKptr i32
BASEID array
BASEname array or buffer (also implicit via BASE cmd)
BTARG array or buffer
BUFfer array
COUNT i32
DEBUGging i16
INFObuf array
ITEM array or buffer
LIST array
MODE i16
NEXTptr i32
OUTbuf array
PASSword array or buffer
PATHS i16
QUALifier array or buffer
RECNUM i32
RECORDS i32
SETname i16 or array or buffer
STATus array (implicitly set by most DB intrinsics)
TEXT array or buffer
UVAR1 array
UVAR2 array
"buffer" means one 16-bit number, one 32-bit number, or text (must
be in quotes if not a single token). Note: SETArray treats the
variables marked as "buf" as though they were "array"
variables.
"array" means several words of data, which may be provided as
16-bit numbers, 32-bit numbers, or text (must be in quotes), or
any combination. A standalone comma (without a value preceding
it) means "leave 1 16-bit word unchanged". Values may be
followed by a ":" and a repeat count (e.g.: 9:4 is equivalent to
9 9 9 9)
A value of BLANKS (or NULLS) will blank (or null) the variable.
If numeric value follows an odd-length string, a single byte
will be skipped (wasted) before the numeric value is inserted.
(I.e., numeric values always start at even-byte boundaries.)
boolean options:
[no]ACK report "ok" if status = 0 or 1
[no]ACKALL
[no]ALLOW1
[no]AUTO1
[no]DEBUG1
[no]DEBUG2
[no]DEBUG3
DECimal
HEX
LISTHEX
NAMEs
NUMbers
OCTal
[no]ONEOPEN
[no]PAGING paginate crt output
[no]PRIVmode
[no]SHOWSTAtus report STATUS variable after calls
[no]SYNLEN report syn chain lens
[no]TIMEs report CPU/Elapsed
[no]TURBO true: not pre-turbo IMAGE database
USERmode
Example:
set buffer "This is a test" 0
set buffer , "XX" (skips the first 2 bytes)
STATus
Calls DBSTATUS:
dbstatus (status, outbuf, bytes)
Note: DBSTATUS is not available from NM DBDRIVE.
To simply see the STATUS variable, do: SHOW STATUS
STUFFBTI [options]
Options are:
# ...high range on dbput values (0..#)
(default = 5)
ALL [LEAD, NONE, TRAIL]
BASIC [# defaults to 1 (if not already specified)]
[defaults to FINDP4 (if not already specified)]
noBTREE
noDELETE
EDITLOCK
FINDI1 \
FINDP4 > mutually exclusive
FINDZ2 /
LEAD
LOCK
NONE
SCHEMA ...shows desired schema and exits command
SETnum #
TRAIL
(SS: I have no idea what this command does at this point
(I'm updating this help file, and I can't remember this
command at all!))
Defaults: # is 5, FINDP4, LEAD, NONE, TRAIL, DELETE
Puts entries into specified set# (default: SETNAME's value),
of the form:
Z2 P4 I1 X32 (where X32 = text describing data)
For the Z2 & P4 fields, if LEAD is on, values with a leading
sign character/digit are entered (positive, zero, and
negative).
For the Z2 & P4 fields, if NONE is on, values with no sign
character/digit are entered.
For the Z2 & P4 fields, if TRAIL is on, values with a trailing
sign character/digit are entered (positive, zero, and
negative).
Thus, if # is 1, and LEAD/NONE/TRAIL are all on, we'll DBPUT
entries with:
+1, 1, -1, 1-, 1+
UNLOCK [mode]
Calls DBUNLOCK:
dbunlock (baseid, setname, mode, status)
UNUSE
Closes the current 'USE' file ... this command is normally
never used or needed.
UPDATE [mode]
Calls DBUPDATE:
dbupdate (baseid, setname, mode, status, list, buffer)
UPDATEALL
Rewinds current set, and calls DBGET/DBUPDATE for every record
in the set with the current LIST variable. Serial Mode DBGETs
are done (does not change global MODE variable).
USEq filename
Tells DBDRIVE to start reading commands from the specified
file. Note: USE files may be nested up to a depth of 31. A
control-Y cancels all currently open USE files.
VERsions
Reports versions of most IMAGE intrinsics, the Reference
Manual, and most utility programs (DBxxxxx.PUB.SYS).
What
Reports value of all DBDRIVE variables.
XBEGIN [mode]
Calls DBXBEGIN:
dbxbegin (baseid, text, mode, status, text'len)
XEND [mode]
Calls DBXEND:
dbxend (baseid, text, mode, status, text'len)
XUNDO [mode]
Calls DBXUNDO:
dbxundo (baseid, text, mode, status, text'len)
----------------------------------------------------------------
ModeNames for DBGET and LIST:
Name Value
----------- -----
BACKCHained (6) \
BACKSERial (3) \
CALCulated (7) \
CHAINed (5) \ valid modes for GET and LIST
DIRECTed (4) /
REREAD (1) /
PRIMARY (8) /
SERial (2) /
----------------------------------------------------------------
----------------------------------------------------------------
Modes
For more information on modes, type: HELP MODENAMES or
HELP OPENMODES
Note: "mode" may be changed, temporarily, by using the phrase
"MODE = <modevalue>" after most command names (and
before any other options to the command)
----------------------------------------------------------------
DBDrive 20201012