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 [=] (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 ::= < 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 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 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 " 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] [ [ # | 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 ] [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 [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 = " after most command names (and before any other options to the command) ---------------------------------------------------------------- DBDrive 20201012