DB META Commands

All DB file related meta commands.

CLOSE_DB

CLOSE_DB <filename>

Closes the named DB file. If all “save to” DB files are closed, items will be saved to the program’s local DB file. This only closes the last DB file opened with CREATE_DB or USE_DB.

CREATE_DB

CREATE_DB <newdbname>,<options>,<DUPLICATE=dupoption>,<SIZES=sizoption>

Creates a DB file to store question entries, variables and table specifications. After the DB file is created, it is kept open with read-write access.

Valid Options

  • ENTRIES= – Maximum number of entries allowed. The default is 505. (E)
  • ECHO – Displays a message when you get an item from the DB file; default is to not echo.  (EC)
  • MAYBE_CREATE – If the DB file exists in the current directory, a new one will not be created, and instead the existing one will be opened in ReadWrite Mode. (MCR)
  • TEST – A test mode file is one with a directory only, it is zero bytes large.

DUPLICATE=dupoption Determines what the program will do when it encounters duplicate names. (D)

Valid dupoptions

  • ERROR Prevents you from storing a duplicate item and displays an error message (this is the default).
  • QUIET Replaces the existing entry with the new one of the same name, without displaying a warning.
  • REPLACE Replaces the existing entry with a warning (like Duplicate=Warn) but helps keep your db file from getting filled up with multiple versions of items since it deletes the old entry and, if the new entry is the same size or smaller, uses that same space again.
  • WARN Replaces the existing entry with the new one of the same name, but displays a warning message.

SIZES=sizoption Lets you specify the number of entries (ENTRIES=) by using some preset values rather than having to fill in the values. (S)

Valid Sizoptions

    • SMALL
    • MEDIUM
    • LARGE
    • LOCAL
    • PREPARE.

Sizoptions Values

    • SMALL=500
    • MEDIUM=1000
    • LARGE=5000
    • LOCAL=1000
    • PREPARE=3000

To change the settings for these sizes, use the >DB_SIZES command.

EXAMPLE:

>CREATEDB newdb, EC, D=WARN, S=LARGE

This creates a DB file called NEWDB with the LARGE number of entries (5000), will generate a message when you get an item from the DB file, and will display a warning when replacing existing items.

If the DB files you create are usually the same size, put the >DB_SIZES command in your INITIAL or MENINITIAL file instead of having to put it in your spec file every time.

You can have multiple DB files open with write access and can put items directly into any of the ‘save to’ DB files. You can have a maximum of ten DB files open at any one time. Use >RESET_DB to close all DB files and >CLOSE_DB to close one DB file.

EXAMPLE:

>CREATEDB db1,D=W
>CREATEDB db2,D=W
>CREATEDB db3,D=W

~DEFINE-

db1^loc1:[5^1.5]
db2^loc2:[6^1.5]
db3^loc3:[7^1.5]

>LISTDB db1
LOC1 ‘’ type = 1, g1=0026, g2= 15, g3= 0, ver = 1

>LISTDB db2
LOC2 ‘’ type = 1, g1=0026, g2= 15, g3= 0, ver = 1

>LISTDB db3
LOC3 ‘’ type = 1, g1=0026, g2= 15, g3= 0, ver = 1

“db1^loc1” directs the variable loc1 to the DB file db1.

See also: >USE_DB, >DB_SIZES, >CLOSE_DB, and >RESET_DB. 

DB_SIZES

DB_SIZES=e1, e2, e3, e4, e5

Sets default values for the number of entries in DB files when you use the >CREATE_DB SIZES=option.

You must enter five numbers, and follow each number with a zero as a place holder. Each number corresponds to the SMALL, MEDIUM, LARGE, LOCAL, and PREPARE options to the SIZES= option of the >CREATE_DB command. The default values for the number of entries are SMALL=500, MEDIUM=1000, LARGE=5000, LOCAL=1000, PREPARE=3000. Use zero if you want to keep a number at the default.

EXAMPLE:

>DBSIZE= 0 0, 0 0, 10000 0, 0 0, 0 0

This example will change the number of entries for a LARGE DB file from 5000 to 10000, and leaves the rest of the numbers the same.

Since the local DB file is not opened until you attempt to make an item when no other DB files are open (in read/write mode), you can control the size and duplicate parameters of the local DB file before it is opened.

If you are not creating your own DB files, you can set these numbers so that they create large LOCAL (default system) DB files which are less likely to run out of room. Keep in mind, however, that larger DB files will slow down Mentor’s setup time. The LOCAL default also affects the number of tables Survox utilities can create in one run. To allow the utilities to create approximately 5000 tables per run, set the LOCAL value to 50,000.

EXAMPLE:

>DBSIZE= 0 0, 0 0, 0 0, 50000 0, 0 0

For DB size LOCAL you can set any of the DUPLICATE= options by specifying the letter of the option after the second number.

EXAMPLE:

>DBSIZE= 0 0, 0 0, 0 0, 2000 0 w, 0 0

The previous example opens the local DB file with DUPLICATE=WARN, overriding the default DUPLICATE=ERROR. The local DB is also increased to 2000 entries; all DB files are opened with the default number of entries listed above.

Specify only the letter of the option and not DUPLICATE=.

Valid Options

  • E for error (default)
  • Q for quiet
  • R for replace
  • W for warn

For DB files other than LOCAL, you must set the duplicate option with either the >CREATE_DB or >USE_DB command.

A default >CREATE_DB with no specifications for ENTRIES= or SIZES= makes a DB size of SMALL.

~PREPARE COMPILE creates a DB size of PREPARE.

You can also include >DB_SIZES in your MENTINITIAL file. This will cause the DB settings you specify to be in effect any time you run Mentor or Survent.

Use >-DB_SIZES to set number of entries back to the default values. 

DB_STATUS

Displays a list of currently open DB files in search order, noting which are ReadOnly and which are ReadWrite. DB files opened ReadWrite indicate ReadWrite access while ReadOnly files are listed by name only.

EXAMPLE:

>DB_STATUS

There are three of a maximum of ten DB files opened. Listed below are the DB files open. They are listed in search order.

c:\acme\j1357\db3.db with ReadWrite access
‘LOCAL’ DB file with ReadWrite access
c:\acme\j1357\db2.db
c:\acme\j1357\db1.db

END_OF_FILE

Causes an end-of-file on the currently opened spec file. Use this command to indicate the end of a >FILE_TO_DB item.

LIST_DB

LIST_DB <options>

Lists entries in a DB file; the default is to list all entries. Groups of items can be selected by variable type or by specifying a mnemonic pattern. If more than one DB file is open, you must specify which to list. The listing can be sent to the console and/or an ASCII file. Use >TERMINAL-PAUSE=# to pause after nth line prints to the screen.

You will get a message if no items are listed. LIST_DB and LIST_DB_CONTENTS do the same thing.

Valid Options

  • dbname – Dbname is any open DB file, and is not required if only one DB file is open. If not specified, a comma must be entered as a place holder if anything follows it on the line.
  • Listname – Name of the ASCII file which will contain the listing. When a list file is specified the file will be given the extension DCL. A plus sign (+) in front of the listname will send the listing to the console and to the list file. If left off, a comma must be entered as a place holder if anything follows it on the line; output will go to the console only.

SORT=<sort_option> Specifies how to sort the DB file and which items to display either to the console and/or DB list file.

Valid Sort Options

  • APPEND – Append to the DCL file if it’s there, otherwise append to a new file.
  • LOCATION – Lists items in the order they were created in.
  • NAME – Lists all items sorted by name (default). It is not necessary to specify SORT=NAME, just >LISTDB dbname.
  • QQNUM – Lists only items that have a question number, meaning items that were made by the PREPARE program or ~DEFINE PREPARE=.
    • The list is sorted on the qqnum. You can further qualify this sort by specifying a specific range after -QQNUM.
  • -QQNUM – Causes the sort to include items that do not have a question number. These are items made in Mentor such as data variables or table definitions.

EXAMPLE:

>LISTDB rrunr,+rrunr,SORT=QQNUM(QN1-QN4)

In this example, QN1 is the beginning and lowest name and QN4 is the highest name that will be included in the list.

TYPE=<option> States the specific variable types which should be listed.

Valid Type Options

  • ALL – Lists all items.
  • TABLES – Lists all tables.
  • TABSETS – Lists all table sets.
  • VARIABLES=ALL – Lists all variables.
  • VARIABLES=# – Lists specific variable types.
    • More than one number can be used here.
    • You can use the numbers 1-8, where:
      • 1 – VARIABLE ($|$S)
      • 2 – Not used
      • 3 – FIELD (=)
      • 4 – (#)
      • 5 – NUMERIC
      • 6 – CAT (^) (Category question types are deprecated)
      • 7 – TEXT ($T)
      • 8 – ($P)

EXAMPLE:

>LISTDB demo,fieldvars,TYPE=VAR=3

PATTERN=(pattern1,pattern2,…patternx) Specifies a mnemonic pattern which the variable names must match to be included in the listing. The pattern may include alpha or numeric characters, and wildcards such as *, ?, or #.

The patterns may be separated by a comma or space.

EXAMPLE:

>LISTDB work,,PATTERN=(te*)
>LISTDB demo,,PATTERN=(QQ*, a*, te??????)

TEMPLATE=<“text ! and|a new line “!” here” &&> May state text to be listed along with each variable in the list. The template may be extended beyond one line by closing the quotes and using & at the end of the first line; the maximum length of a template string is 300 characters. An exclamation point (!) in the template is the place holder for the variable name, and a vertical bar (|) will start a new line.

Lines generated with the TEMPLATE option cannot exceed 132 characters. Use line breaks (\\) to break long lines at 132.

EXAMPLE:

>LISTEB demo,+listoe,TYPE=VAR=17, &&
TEMP="~SHOW !|"

>LISTDB demo,field,TYPE=VAR=6,TEMP="'FIELD"&&
" variable: !|~SHOW !"

The list file can be edited and used for getting multiple entries from a DB file without specifying them individually. This can be done by typing && before each name and then using &filename.DCL to bring in the file during a PREPARE run.

EXAMPLE:

>LISTDB RRUNR,+RRUNR

This example lists the contents of the DB file RRUNR to the screen and to the file RRUNR.DCL (DOS and UNIX). The default sort lists all items alphabetically.

RESET_DB

Closes all DB files currently opened with either a >CREATE_DB or >USE_DB command.

USE_DB

USE_DB dbname,<roption>,<EC>,<DUPLICATE=doption>

Opens a DB file. You can have multiple DB files open with write access and can put items directly into any of the ‘save to’ DB files (see example under >CREATE_DB).

Valid Options

  • dbname – The only required parameter.
    • You can specify “ * ” as the dbname in conjunction with a name specified on a >STUDY_NAME command.
  • roption – Read option, either RO or RW.
    • READ_ONLY(RO), lets you read entries from the DB file.
      • This is the default.
    • READ_WRITE(RW) lets you read entries from the DB file and write (and save) entries to the DB file.
  • EC – ECHO displays a message when you get an item from the DB file.
    • The default is to not echo.
  • DUPLICATE= – Determines what the program will do when it encounters duplicate names.

Valid doptions

  • ERROR – prevents you from storing a duplicate item and displays an error message (this is the default).
  • QUIET – replaces the existing entry with the new one of the same name, without displaying a warning.
  • REPLACE – replaces the existing entry with a warning (like D=W) but helps keep your DB file from getting filled up with multiple versions of items since it deletes the old entry and, if the new entry is the same size or smaller, uses that same space again.
  • WARN – replaces the existing entry with the new one of the same name, but displays a warning message.
Next Topic