The database

The database (DBA) facility is an information storage and retrieval subsystem used for organization of and access to information related to spectrum data. For 1D applications, the database might contain information pertaining to baseline points, integral segment definitions, integral volume measurements, resonance positions, and line widths. For 2D applications, the database might contain information related to cross-peak positions, cross-peak widths, volumes, resonance assignments, and tile limits. The database is flexible enough that it can be used with any type of information, regardless of whether it relates to NMR data.

For efficient access to the information within the database, all data are contained in a single binary file called a database file. Since this file is binary, you cannot examine it directly. There are, however, provided several tools for accessing the database information from within FELIX and for generating useful ASCII output. Database-access commands also allow writing of any entity in the database to an ASCII file and reading of the ASCII files back into the binary database.


Structure of the database

Each set of information is stored in the database as an individual entity. An entity can be thought of as a folder or container that holds zero or more units of a particular type of data. An item is one unit of data within an entity. All items in an entity have a single format that is defined in an auxiliary file called a schema. For example, the set of information that corresponds to one particular cross peak is stored in the database as one item, within an entity that may itself contain many cross peaks. Likewise, assignment information for one specific assignment might be stored in the database as a single item within an entity of multiple assignments.

An item itself is composed of several data elements. Each individual datum within an item is an element. Thus, one cross-peak item contains center and width elements for all dimensions, and one assignment item contains atom-name and chemical-shift elements. The element is the smallest unit of information in the database. An element is always one integer, one floating-point value, or one ASCII string. Element names and types within an item are defined by the corresponding schema file when an entity is built.

Entities are called Tables throughout the graphical interface. The two terms may be used interchangeably for the most part. See "Spreadsheet interface" on page 85.


The database schema

The schema file is the format descriptor for an entity. It tells how many elements that an item of this entity must have, as well as the internal and external format of each element. Schema are stored in the schema subdirectory and are prefixed with the schpfx symbol. Schema files are extremely format sensitive. If you want to build your own schema file, the order of the format descriptions must be the same as in the schema files provided. Building your own schema files provides a mechanism to store and output database information in any format you desire.

An example schema for storing 1D peaks (the line numbers are for explanation purposes only) is:

1	c**asg.sch
2 asg 5
3 item i k 01 06 (1x,i5)
4 cenpnt r k 01 10 (f10.5)
5 wid r 01 10 (f10.5)
6 cenppm r k 01 10 (f10.5)
7 name c 08 10 (2x,a8)

where:

Line 1:

A filename record, of the form c**, filename (a3,a)

Line 2:

A descriptor record, of the form schema_name, number_of_elements (a8,i2). The number of elements is calculated for one occurrence of each element.

Line 3:

The first element. It must be item, as this is the primary access key for database items. Always set the key flag for the item element by including the letter "k" after the type identifier. Subsequent elements can be named at your discretion. The formatting scheme for the element names and all subsequent parameters must be:

     (a8,1x,a1,1x,a1,i3,i3,1x,a32)

The definition for each element in the schema is:

     element type key internal_size external_size I/O_format

where:

element = (a8) element name

type = (a1) r = real i = integer c = ASCII

key = (a1) k = key on this element for sorting

internal size = (i3) binary data size (words)

external size = (i3) size of ASCII text of data

I/O format = (a32) FORTRAN format of element

In this example, all items within this entity would contain:

     item, cenpnt, wid, cenppm, name

with a format of the form:

     (1x, i5, f10.5, f10.5, f10.5, 2x, a8)

An example of the schema used for picking and storing multi-dimensional data is:

1	c**xpk.sch
2 xpk 6
3 item i k 01 06 (1x,i5)
4 #begin
5 cen# r k 01 10 (f10.3)
6 wid# r 01 10 (f10.3)
7 ptr# r 01 06 (1x,i5)
8 asg# r 16 18 (2x,a16)
9 #end
10 cc r 01 06 (1x,f5.2)

In this instance, the number of elements stored in the database depends on the dimensionality of the matrix. For 2D matrices, two center position elements are created, named cen1 and cen2. This applies to all the elements that fall between the #begin and #end statements. Similarly, for 4D data, positions for four assignment names (asg1, asg2, asg3, asg4) are created. When building a new user-defined entity, the value of occur in the build string is used to determine the number of occurrences in a receptive entity (see below). You encounter this option when you build an entity from scratch:

 > dba entity build entity_name schema occur

The dba entity build command creates one new empty entity called entity_name. This new entity stores information in the format defined by the schema file and is repeated the number of times set by occur. More information on this procedure is found below.


Creating database information

Certain program commands extract spectrum information and it directly into a database file. These commands look at the current values of specific symbols to determine which files are current for that application. For this reason, opening a database file must precede execution of these commands. For example, the drx, pic, and vol commands need to access peak information before drawing peak boxes, picking more peaks, and generating volumes. Since this information is stored in the database file, this file must be open and current. By default, the commands that store spectrum information in the database automatically build their own entities. For example, the pic command uses the value of the reserved symbol pksent to determine where to put the subsequently picked peaks. Likewise, the vol command uses the value of the reserved symbol volent to store ND volume information in the entity.


Database command structure

Since the database facility is fairly sophisticated, we have developed a database command mode separate from the FELIX command language. To enter database mode, enter:

 > dba

Entering this command changes the command prompt to DBA>, indicating that only database subcommands may be entered. The subcommands and their required parameters may be entered on a single line (128 characters maximum). After executing the command statement, the DBA> prompt reappears, waiting for the next subcommand. To return to the FELIX prompt, enter one of the database subcommands bye, exit, or quit. Alternatively, you can place an entire database command statement (starting with dba) on one line. After execution of the dba command, the program returns to the FELIX prompt.

In summary, the basic dba subcommands are:

dba

Activate database command mode.

dba bye

Exit database command mode.

dba exit

Exit database command mode.

dba quit

Exit database command mode.


Database files

To build a new database file from scratch, you must issue the appropriate command for constructing a new file:

 > dba file build file_name confirm

The file_name parameter names the file with the default .dba extension. This file is placed in the directory defined by the dbapfx reserved symbol. The confirm parameter is used to overwrite a database file that already exists. A "y" overwrites a database file with the same name automatically, and an "n" does not overwrite the database file (default).

Once a database file is built, you must explicitly open it:

 > dba file open file_name

Once the database file is opened, you can subsequently pick peaks, integrate volumes, make assignments, or otherwise access spectrum information.

To save the database file contents you must explicitly close the file:

 > dba file close confirm file_name

The confirm parameter requires the values s or q. The s option saves the current database file contents to disk with all changes; q discards all the changes you've made to the database since the database file was first opened. To change between databases, you must first close the current database file before opening or building a new one. The file_name parameter is used for saving the DBA to another filename and is optional.

To list the directory (contents) of the current database file, use the show command:

 > dba file show

To determine whether the contents of a database have been modified, use the mod command:

 > dba file mod symbol

If the database has been modified since it was last saved, the resultant value of symbol is 1. If the database has not been modified, the value of symbol is 0.

To write out all database entities into a set of ASCII files, use the command:

 > dba ascii dir_name

This command writes out all entities into the dir_name directory.

From this directory you can restore a database using the command:

 > dba restore dir_name

This destroys all entities in the current database, so it should be used only with a clean database.

dba file subcommands

In review, the dba file subcommands are:

dba file open file_name

open database file

dba file close confirm file_name

close database file

dba file delete confirm

delete database file

dba file build file_name confirm

build database file

dba file show

database directory

dba file mod symbol

database modified query

dba file ascii dir_name

write ASCII files

dba file restore dir_name

restore database


Database entities

As mentioned above, a schema file, which is created when an entity is built, defines the format for all items in an entity. The schema thus functions as the item template for an entity: it contains the element names, data types, and ASCII text format that precisely define the contents and layout of every item in that entity. See "The database schema" on page 68.

You can build an entity for storing spectrum information using the command:

 > dba entity build entity_name schema occur

The dba entity build command creates one new empty entity called entity_name. This new entity stores information in the format defined by the schema file and repeats it the number of times set by occur. For example, if you want to build an entity for storing NOE buildup intensities at 6 mixing times, the format for a single intensity could be defined in the schema, and the intensity field would be repeated occur (i.e., six) times.

Entities can be deleted from the database using the command:

 > dba entity delete entity_name

To list the contents of an entity on the screen, use the show command:

 > dba entity show entity_name

This prints the contents of the specified entity on the screen in the format defined by the schema for that entity.

To generate an ASCII file of an entity for output, editing, or analysis, use the command:

 > dba entity write entity file_name

The first line of this file is a copy of the filename. The next line is the schema name and number of occurrences. The other lines in the file are the data contents of the entity written in the defined schema format.

To read the ASCII file of an entity that you have modified back into the program, use the command:

 > dba entity read entity file_name

This command reads a file where the first line is a filename. The next line after the filename must be the schema name and number of occurrences. The remaining lines of the ASCII file are read, as items to be stored in this new entity, using that schema format. This feature is most useful for editing existing entity information rather than for building new information from scratch. Therefore, we suggest that you use the dba entity read command in conjunction with the dba entity write command.

In some instances, you may want to read items of one entity while directly altering another entity. The command:

 > dba entity current entity name

addresses this need by presetting the item buffer to one entity without specifically loading an item from that entity. More information about the item buffer. is provided later in this section. See "Database item lists" on page 79.

Entities can be copied to a new entity based on the same schema with the command:

 > dba entity copy old_entity new_entity renumber

When renumber is zero, all item numbers remain the same. When renumber is non-zero, all items are renumbered so that the first item is number renumber, and all other item numbers increment by one.

An entity can be converted to a new entity based on a slightly different schema with the command:

 > dba entity filter old_entity new_entity new_schema constants

For every item in the entity, all elements that match name for name between the old schema and the new schema are copied. Any elements of the new schema that are not present in the old schema may be filled in with a constant value by including constant parameters on the command line in the form element=value.

Selected ranges of elements for every item can be put into a file with the command:

 > dba entity put entity file_name first_elm last_elm

For every item in the entity, a line is written to the file containing the values of the elements in the range from first_elm to last_elm, inclusive. Both first_elm and last_elm are integer element numbers. Optionally, if the file_name is entered as "#", then the lines are appended to the current FELIX output file. See the descriptions of the opn and put commands in Appendix A for more information about output files.

The schema file that an entity is built from is available with the command:

 > dba entity schema entity symbol

This sets the value of symbol to be the name of the schema file, without the prefix or .sch extension.

The spreadsheet interface to the database is described below.

The database also provides a command for integrity testing an entity. All entities have special indexing trees for all keyed elements (elements that have a "k" in the schema file). These index trees provide fast search of and access to items in the entity. The entity can be tested for integrity with the command:

 > dba entity test entity

An entity must pass this test. There is no way to recover an entity that fails. However, if an entity does fail, it is usually only on some of the keyed elements and not on all elements. In most cases, you can still write the entity to a file (dba entity write) and then read the file back into another entity (dba entity read) and the entity integrity will be restored. This command is for debugging purposes only.

dba entity subcommands

In review, the database entity subcommands are:

dba entity current entity_name

activate entity

dba entity read entity file_name

read ASCII file

dba entity write entity_name

write ASCII file

dba entity delete entity_name

delete entity

dba entity build entity schema occur

build new entity

dba entity show

show entity contents

dba entity copy old_entity new_entity renumber

copy entity

dba entity filter old_entity new_entity new_schema constants

filter entity

dba entity put entity file_name first_elm last_elm

put entity to file

dba entity schema entity symbol

get schema file name

dba entity test entity

test entity integrity


Database items and elements

An item is defined as one unit of data within an entity. An item itself is composed of several data elements. The individual datum within an item is an element. The element is the smallest unit of information in the database. An element is always one integer, one floating-point value, or one ASCII string. Element names and types within an item are defined by the schema file when an entity is built. The only restriction is that the first element within an item always be an integer with an element name of item.

Since items can contain a number of elements (up to 20 total) of several types (integer, floating point, ASCII), each with its own unique element name, a simple and universal item interface is essential. To this end, the database command interface provides one generic item buffer and a collection of item and element subcommands for accessing this buffer. These subcommands allow you to move data values into and out of any element of any item of any entity. The item subcommands move items from an entity into the item buffer and store items back in their place in the entity. The element subcommands move individual elements from the item buffer into symbols, then store new values back into elements in the item buffer.

To load an item into the item buffer, use the command:

 > dba item load entity.item#

The item# is the identifying marker for that item and is simply the item element.

To load any element from the item buffer into a symbol, use the command:

 > dba element load element symbol

This loads the value of the specified element into the symbol you've named.

To store information back into the database file, you must first store the value of an element in the item buffer, which must then be stored in an item in the entity. For example:

 > dba element store element value

stores the current value in the specified element in the item buffer.

To store the item buffer back in your database file, the above command would be followed by:

 > dba item store entity.item#

Database items can also be deleted from an entity using the command:

dba item delete entity.item#

Only the specified item is affected. No renumbering of other items occurs. This command is useful for permanently removing spectrum information from the database file.

To show the current contents of an item, use:

 > dba item show entity.item#

The dba item show command prints the contents of one item of one entity. To show the contents of the item buffer itself, you can use dba item show 0 (the item buffer is item number 0 by default). Likewise, the command:

dba element show entity.item#.element

shows the contents of the specified element to the screen.

In conclusion, to use the dba item and dba element commands to change the current value of an element within an item, you follow these steps:

1.   Load the desired item from the entity to the item buffer.

2.   Load the desired element into a symbol.

3.   Store new values in an element.

4.   Store the item back in the database.

Alternatively, to create new items you would:

1.   Build a new entity from a schema.

2.   Make the new entity current.

3.   Store values in all elements.

4.   Store the item buffer to any one item.

The database also hasn some shortcut methods for loading and storing elements. One method allows you to bypass the use of the item buffer and get values directly from the entity. This is most useful if you only need a single element value from an item. The command:

 > dba element load entity.item#.element symbol

loads one element directly from the entity into a symbol. This is equivalent to the two commands:

 > dba item load entity.item#
 > dba element load element symbol

Likewise, to store a value to a single element in an item, the command:

 > dba element store entity.item#.element value

is equivalent to the three commands:

 > dba item load entity.item#
 > dba element store element value
 > dba item store entity.item#

The second shortcut method allows loading or storing adjacent elements in an item with a single command. The elements must be adjacent. With the dba element load command, if the command line has multiple symbol parameters, then multiple elements are loaded to those symbols. Likewise, with the dba element store command, if the command line has multiple value parameters, the multiple values are stored to those elements. In the item buffer method, the command format is:

 > dba element load element_1 symbol_1 ... symbol_N
 > dba element store element_1 value_1 ... value_N

while for the entity direct method, the command format is:

 > dba element load entity.item#.element_1 symbol_1 ... symbol_N
 > dba element store entity.item#.element_1 value_1 ... value_N

These different access methods provide the fastest possible runtime access to the database contents. The basic guidelines for speediest access are:

1.   To load multiple elements and then store one or more elements, use the item buffer.

2.   To load just one element, use the entity direct method.

3.   To load or store multiple adjacent elements, use the multiple parameters method.

dba item and element subcommands

In review, the dba item and dba element subcommands are:

dba item load entity.item

load an item to the item buffer

dba item store entity.item

store item buffer to an item in the entity

dba item show entity.item

print contents of an item

dba item delete entity.item

delete an item from an entity

dba element load element symbol

load an element from the item buffer

dba element load entity.item.element symbol

load an element from an entity to a symbol

dba element store element value

store a value into an element of the item buffer

dba element store entity.item.element value

store a value into an element of an entity


Database item lists

The database also has utilities for fast read-only perusal of entities. In addition to accessing explicit items one by one via the item buffer, you can also generate and manipulate complete lists of item numbers. Because these lists occupy the 1D buffers, the buffers may require configuring to contain large lists. These lists know only how to hold pointers to items in an entity and do not actually store data-items themselves. In using these pointers to access spectrum information, you must still specify specific items and elements using the commands described above.

The purpose of item lists is to help maximize the speed of database queries. Instead of explicitly loading every item one at a time and testing various elements for a condition to see if that item meets the criterion, the item list commands generate the set of items that meet a criterion in a single step. You can then work with just those items in the list, knowing that they satisfy the criterion. Because you can avoid looking at every item explicitly, you save considerable time.

As an example, let's find a range of items within a database. This is accomplished using the following dba list command sequence:

 > dba list range list # entity element low high symbol

More specifically, the command statement:

 > dba list range 1 xpk:peaks cen1 200 500 pknum

puts the item numbers of all of the cross-peak footprints from the entity xpk:peaks, whose centers in D1 (cen1) are between 200 and 500 point units, into list "1". The number of items that meet this criterion is returned in the symbol pknum. You can then use dba list show list_# to view the resulting list. For example, if seven items meet the above criterion, list 1 might appear as:

	slot #=	1	item#=4
slot #= 2 item#=309
slot #= 3 item#=17
slot #= 4 item#=90
slot #= 5 item#=8
slot #= 6 item#=5
slot #= 7 item#=99

In this list, each slot number contains an item number. For use within a macro, the following sequence prints the D1 centers on the screen, one per line:

1	dba list range 1 xpk:peaks cen1 200 500 pknum
2 for loop 1 &pknum
3 dba list load 1 &loop tstitm
4 dba element load xpk:peaks.&tstitm.cen1 cenval
5 ty peak=&tstitm D1 center=&cenval
6 next

The first line creates a list of cross peaks, with centers between points 200 and 500 in the first dimension. The second line sets up a loop to move through each item in the list. Because pknum number of peaks were found using the dba list range command, the loop executes pknum cycles.The third line loads each item from the list, saving the item number as the symbol tstitm. The fourth line loads the value of an element within the selected item to the symbol cenval. Line five prints the value of the symbol cenval, and line six exits the for loop. Using this logic, values for any element in the database, or even database items themselves, can be modified.


dba list subcommands

The dba list subcommands are given below, with brief descriptions of their functions.

dba list add1 list value

This command appends one value (item #) to the end of a list. If the value is already in the list, the item # is not added again.

dba list count list symbol

This command loads the count (number of item #'s) of a list into a FELIX symbol.

dba list del1 list value

This command deletes one value (item #) from a list. If the value is not found in the list, no deletion occurs. Note that delete looks at the value in a slot, not at slot numbers.

dba list difference list1 list2 list3

This command builds a new list that is the set difference of two lists. The resulting list number may be one of the input lists. The result list3 contains only those item numbers from list1 that are not present in list2.

dba list entity list symbol

This command extracts the entity ID number from the given list. The ID number is the same value as returned by the db$entity() function.

dba list find list value symbol

This command finds one value (item #) in a list and puts the result into a symbol. If the value is not found in the list, the result is zero. When the value (item #) is found, the result is the slot number containing that item #.

dba list intersect list1 list2 list3

This command builds a new list that is the set intersection of two lists. The result list3 may be one of the input lists. The result list3 only contains those item numbers that were in both list1 and list2.

dba list load list slot symbol

This command loads the current contents of one slot of one list (an item#) into a FELIX symbol.

dba list match list entity element match_string symbol

This command builds a list of all items where the given element matches a wildcard string. This command is only applicable for character-string elements. The normal rules for using wildcards in the match string apply. The number of items placed in the list is returned in symbol.

dba list exact list entity element match_string symbol

This command builds a list of all items where the given element matches a string taken literally, that is, the * is not interpreted as a wildcard but as a letter. This command is only applicable for character-string elements. The number of items placed in the list is returned in symbol.

dba list move list1 list2

This command copies list1 to list2.

dba list range list entity element low high symbol

This command builds a list of item numbers in a range based on the values for a single element. You specify an entity name to search, an element name to select, and the desired range values. The result is a list, built to contain all the item #'s having that element within the requested range. The item numbers are ordered such that the element values are in increasing order. The number of items placed in the list is returned in symbol.

dba list show list

This command shows the contents of one list.

dba list sort list key up/down

This command sorts the contents of one list. For now, the basic sort is limited to elements containing numeric fields. The list may be sorted in ascending or descending order. Item numbers are rearranged in the list so that they occur in the sorted order. You can sort on a key other than the item number in two ways. You can sort a list of item #'s, keying on any numeric element in that item. In this method, the item numbers are rearranged so that the values of the key element occur in the sorted order. The second way to sort a database list involves the 1D workspace WORK. For a list with N item numbers, load the first N points of WORK with real values, one for each item# (that is, WORK(i) = function (item# at LIST(i))). Instead of an element number or name for the sort key, use the name "WORK" as the key. The item numbers (and the contents of WORK) are rearranged so that the values in WORK occur in sorted order. This lets you order the item numbers in a database list based on any criterion that you can quantify.

dba list union list1 list2 list3

This command builds a list that is the set union of two lists. The resulting list3 may be one of the input lists. list3 contains the item numbers that were in either list1 or list2.

dba list zero list entity

This command zeros one list by setting the list count to zero and pre-setting the entity owner of this list. A list must be zeroed before you can build a new list from scratch using the dba list add1 command. The new list needs an entity owner to keep track of which dataset the items of this list belong to.

dba list parameters

The dba list parameters are:

element

name of one element in this entity

entity

name of one entity (owner of this list)

high

high value for setting range limits

key

element number or name, as the key to sort on

list

number of one list [range 1 ... n_buffers]

low

low value for setting range limits

match_string

wildcard ASCII string to match against

slot

number of one list slot [range 1 ... list size]

symbol

symbol loaded from contents of slot in list

up/down

sort order: 0=ascending, 1=descending

valu

value to add to or delete from a list


Creating lists of information

The database list subcommands discussed above are specifically designed to let you manipulate arrays of spectrum information. In addition, the database list subcommands let you build lists from scratch using the dba list add1 and dba list range commands. For certain applications, however, we have found it more efficient to provide specific commands for building lists automatically. The xpl command generates a database list of item numbers from cross-peak entities based on the options listed below. These all function as described below and are equivalent to a series of dba list commands, but they operate much more quickly.

Please refer to the xpl command in Appendix A for more information.

xpl subcommands

xpl box list entity d1low d1hi d2low d2hi ... symbol

This command makes a list of all cross peaks inside an ND box. All peaks having center-point values inside the box limits are put in the list. The box may reference outside the current plot limits. The box limits are in points. When d1low is negative, no other box limits are needed. Instead, box limits are defined by using the spot cursor to draw a rectangle around a region of the current ND plot. The value placed in symbol represents the number of items placed in the list.

xpl touch_box list entity d1low d1hi d2low d2hi ... symbol

This command makes a list of all cross peaks inside an ND box. All peaks having at least part of the peakbox touching the box limits are put in the list. The box may reference outside the current plot limits. The box limits are in points. When d1low is negative, no other box limits are needed. Instead, box limits are defined by using the spot cursor to draw a rectangle around a region of the current ND plot. The value placed in symbol represents the number of items placed in the list.

xpl inside_box list entity d1low d1hi d2low d2hi ... symbol

This command makes a list of all cross peaks inside an ND box. All peaks having their full peakbox inside the box limits are put in the list. The box may reference outside the current plot limits. The box limits are in points. When d1low is negative, no other box limits are needed. Instead, box limits are defined by using the spot cursor to draw a rectangle around a region of the current ND plot. The value placed in symbol represents the number of items placed in the list.

xpl line list entity dimension point symbol

This makes a list of cross peaks touched by a line in one dimension. All cross peaks in the entity are candidates because plot limits have no effect. The value placed in symbol represents the number of items placed in the list.

xpl point list entity d1point d2point ... symbol

This command finds all cross peaks touching an ND point. All peaks with their footprints (center plus width) encompassing the given ND point are put in the list. The point may reference outside the current plot limits. The ND point is given in points. When d1point is negative, no other dimensional points are given, instead the point is selected using the cross-hair pointer. The value placed in symbol represents the number of items placed in the list.

xpl range list entity dimension lowpt hipt symbol

This command makes a list of all peaks within a range in the specified dimension. All cross peaks in the entity are candidates, and currently displayed plot limits have no effect. The value placed in symbol represents the number of items placed in the list.

xpl name list entity dimension match string symbol

This command makes a list of all peaks, with an assignment name in that dimension that matches the given character string. The value placed in symbol represents the number of items placed in the list.

xpl frequency list entity dimension freq_list# resolution symbol

This command makes a list of all peaks that align with a frequency list in that dimension within the given resolution. The value placed in symbol represents the number of items placed in the list.

xpl pattern list entity dimension pattern_id resolution spectrum_id symbol

This command makes a list of all peaks, with position in that dimension, that align within the resolution with the given pattern's (pattern_id) frequencies from the Assign database. The generic or spectrum-specific shifts of the frequencies are used, depending on the spectrum_id parameter. The value placed in symbol represents the number of items placed in the list.

xpl clipboard list entity dimension resolution symbol

This command makes a list of all peaks, with position in that dimension, that align within the resolution with the frequencies in the clipboard from the Assign database. The value placed in symbol represents the number of items placed in the list.

xpl proto list entity dimension proto_# resolution symbol

This command makes a list of all peaks, with position in that dimension, that align within the resolution with the given protopattern's (proto_#) frequencies from the Assign database. The value placed in symbol represents the number of items placed in the list.

xpl pt list entity dimension assignment_ptr symbol

This command makes a list of all peaks, with an assignment pointer in that dimension, that matches the given assignment pointer. The value placed in symbol represents the number of items placed in the list.


Spreadsheet interface

The database can be viewed and modified through a visual spreadsheet interface. This section describes the commands of this interface.

Table composition commands

The tbl com(pose) commands define a table from one or multiple entities in the database and then display the table. The options are:

 > tbl com(pose) cre(ate) table_name #_of_rows #_of_cols

This creates an empty table with #_of_rows rows and #_of_cols columns with the table_name name.

 > tbl com(pose) dis(play) table_name

This finishes the table definition and displays it. You fill in the table using the tbl set commands.

You can create tables for whole entities using the following variation of the compose command:

 > tbl com(pose) ent table_name entity_name

There are some specific database entities, which may be a combination of other entities (for example, spin systems) or which may have a stored entity that is different from the table view (for example, peaks or prototype patterns). These entities require specific commands to view them:

 > tbl com(pose) xpk table_name entity_name

creates a peak table,

 > tbl com(pose) pat table_name entity_name

creates a spin-system or pattern table.

 > tbl com(pose) pro table_name entity_name

creates a prototype pattern table.

Table pulldown command

The tbl pul(ldown) command allows you to redefine the .mnu file that is active in the graphical interface for a particular table:

 > tbl pul table_name menu_file

Table icon command

To customize the graphical interface of a table, use the icons to add or change specific table functionalities. The tbl ico(n) command allows you to redefine the icon bar file that is active in the interface for a particular table:

 > tbl ico table_name icon_file

Table navigation from a macro

The tbl jum(p) command allows you to move to a specific location in a table. This moves the active cell or row to that position, too. The options are:

 > tbl jum cel table_name row_number column_id
 > tbl jum row table_name row_number
 > tbl jum col table_name column_id

Table selection

The tbl sel(ect) command allows you to select or highlight a cell, row, column, or the full table. The options are:

 > tbl sel cel table_name row_number column_id

selects (highlights) a cell of a specific row_number row and column_id column.

 > tbl sel row table_name row_number

selects a full row.

 > tbl sel col table_name column_id 

selects a full column.

 > tbl sel all table_name

selects the full table.

Table unselection

The tbl uns(elect) command allows you to deselect or unhighlight a cell, row, column, or the full table. The options are:

 > tbl uns cel table_name row_number column_id
 > tbl uns row table_name row_number
 > tbl uns col table_name column_id
 > tbl uns all table_name

Set a table to an entity

The tbl ent(ity) command sets a table type to a specific entity. This command does not fill in the table with the entity, in contrast to the tbl com(ment) command.

 > tbl ent table_name entity

Querying selection status of a table

The tbl whi(ch) command returns a list of rows or columns that are selected or highlighted:

 > tbl whi table_name list# number_of_items type_of_selection

The number_of_items variable is 0 if none is selected and -1 if all are selected. The selected row or column numbers are returned in the list# list, and the type_of_selection symbol is set to 1 if rows are selected, to 2 if columns are selected, or to 0 if neither rows nor columns are selected.

Querying an item

The tbl get command returns a string of a contents of a cell or row:

 > tbl get cel table_name row_number colum_id string

returns the contents of a cell into string symbol, and:

 > tbl get row table_name row_number string

returns the contents of a whole row into the string symbol.

Deleting a row

The tbl del(ete) command deletes a row from the table_name table:

 > tbl del table_name item_number

Sorting a table by a column

The tbl sor(t) command sorts a table by a selected column and stores the sorted row numbers in a list:

 > tbl sor table_name column_id order list#

where order is descending (0) or ascending (1).

Note: This kind of sorting affects only the spreadsheet view of the entity, not the entity itself

Finding in a table

The tbl fin(d) command finds all instances of items that match a certain criterion and puts them into a list. The command works in a column. The resulting list contains the item numbers. There are two forms -- one for finding strings:

 > tbl fin table_name column_id match_type match_value list# number_of_matches

where match_type can be exact matching (ex) where * are taken literally, or wildcard matching (match), e.g.: a string in a form quot;*abc*".

The other form is for numeric comparisons:

 > tbl fin table_name column_id match_type match_value (match_value2) list# number_of_matches

where match_type can be one of the following types:

eq

equal to match_value

ne

not equal to match_value

lt

less than match_value

le

less or equal to match_value

gt

greater than match_value

ge

greater or equal to match_value

wi

within match_value and match_value2

ou

less than match_value or greater than match_value2

Adding a row

The tbl add command add a new row to the end of a table:

 > tbl add table_name rownumber

The row can then be filled with the tbl set command. The rownumber symbol is returned by the command.

Querying the number of tables active

The tbl who command returns the number of tables active in FELIX in the num_tables variable or the name of the table in the table_name variable, if a specific table is defined in the table# variable:

 > tbl who num_tables
 > tbl who table table_name

Closing a table

The tbl clo(se) command closes a table, but does not destroy the database entity:

 > tbl clo table_name

Querying the number of rows

The tbl row command returns the number of rows in a table:

 > tbl row table_name number_of_rows

Querying the number of columns

The tbl col(umn) command returns the number of columns in a table:

 > tbl col table_name number_of_columns

Setting a value

The tbl set commands allow you to set the value of a row, column, or cell or to set the item number to a particular value:

 > tbl set cell table_name row_id column_id value

This sets the (row_id,coumn_id) cell to value. To set cells in a full row, use this command:

 > tbl set row table_name row_id value value2 ... 

The column command sets the title of the column:

 > tbl set column table_name column_id value

Double-click action

The tbl dbc command allows you to connect a macro to a row double-click, so that double-clicking a row with the cursor executes the macro and passes the row number to the macro:

 > tbl dbc table_name macro_name

Column width

The tbl wid(th) command allows you to set the width of a column in characters:

 > tbl wid table_name column_id width_in_characters

Updating the table

The tbl upd(ate) command allows you to update a table after an entity has been changed:

 > tbl upd table_name

This updates the full table. The

 > tbl upd table_name item_number

This updates a particular item in the row or adds a new row with that item from the entity. The entity update from the table happens automatically.

Querying the item

The tbl ite(m) command allows you to query the row number where a specific database item is shown in the table:

 > tbl ite table_name item_number row_number

The returned value of row_number is greater than zero if it is found or zero in case of error.

Table callback

The callback from a table after selection using pulldowns (.mot files) or icons (.ico files) has the following specification in, for example, the .mot file:

...
item "Select" S NULL NULL "ex select 1" 1 NULL
...

This sends the following command for each cell/row/column selected:

 > ex select 1 table_name item_number row_number column_number

And after the last one:

 > ex select 1 table_name -1 -1 -1

If a full row is selected, the column_number is 0. If a full column is selected, the row_number is 0 and the item_number is 0.