qddb_table provides a table abstraction useful for building reports and spreadsheets. The qddb_table command manipulates tables produced by the qddb_rows command, or with qddb_tabledefine.

Notethatqddb_tableusesrowsandcolumnsbeginningwith1.

qddb_tabledefine
defines a new table and sets up the initial state of the table. All options provided in a qddb_tabledefine command can be changed later with qddb_tableconfigure, qddb_tablerowinsert|delete and qddb_tablecolinsert|delete.

qddb_tabledelete
deletes the given table from memory. Tables produced with qddb_rows may need to be processed to delete tuple and row descriptors before deleting the table.

qddb_tableclear
clears all contents from the table, leaving the number of rows and columns intact. All options and values are cleared and reset to the defaults.

qddb_tablecopy
returns a new table descriptor referencing a copy of the given table. All settings, values, comments, etc. are copied.

qddb_tableeval
recalculates all calculated cells in the given table. The calculations are performed in either row or column order, depending on the setting of the table's -order option. If -autoeval is on, this command usually has no effect.

qddb_tableexpr
evaluates an arbitrary expression with no implicit table or cell association. All range functions must provide an explicit table reference.

qddb_tableexpr_ok
checks the syntax of the given expression without concern for whether the expression can be properly evaluated on any given table.

qddb_tablegetval
returns the contents of the table in one of several formats. In each format, the user can select to display row and/or column titles. If row and column titles are not set, the number of the row or column is shown. The available formats are:

list - an unformatted list of rows; each row is a list of cell values
text - a formatted string, suitable for printing rows - a list of formatted rows, suitable for displaying in a listbox

qddb_tablesetval
accepts a list of rows, where each row is a list of cell values. qddb_tablesetval sets the given table to contain those values. The number of elements in the list must equal the number of rows in the table. Each element in the list must be a list where the number of elements equals the number of columns in the table, and the type of each element must correspond to the type of the column. For example, a 3x3 table of column types

real string real

requires an argument similar to the following:

{
{3.0 {hello world} 211.00}

{2.01 {some string}

121.00} {1.0 {some third string} 1.212} }

qddb_tablecget
retrieves the current value of the given option for the given table. The available options are:

-variable - a variable name to use as for quick access

to cell values

-name

- a symbolic name for the table; must be of the form "[a-zA-Z][a-zA-Z0-9._-]*" -autoeval - whether autoevaluation is on or off

-order

- the default re-calculation order used when cell values change

-title

- a symbolic title for the table -comment - a general comment for the table

qddb_tableconfigure
changes the value of the given option (see above) for the given table. Multiple options may be given in a single command.

qddb_tablesort
sorts the table according to the -sortby and

-ascending options.

Column names provided with -sortby and -ascending may be given either their default numeric names (beginning with `1') or assigned symbolic names.

qddb_tablesummary
returns a new table suitable for building barcharts and graphs. The new table is a summary of each row in the given table. The format and range are on the <x_col>:

qddb_tablerow executes a secondary row command on the given table and row.

qddb_tablerowinsert
appends one new row to the table by default. If the -before option is given, then the row is inserted before the given row. If the -numrows option is given, the given number of rows are inserted or appended to the table. The default number of rows is one.

qddb_tablerowdelete
completely deletes the given row from the table.

qddb_tablerowclear
clears the given row values and options, leaving the row in place. All options and values are cleared and reset to the defaults.

qddb_tablerowcopy
copies the given row and places the copy in the specified location. If the destination ('to') row exists, it is overwritten; if it doesn't exist, it is created. The source ('from') row must exist or an error is returned.

qddb_tableroweval
recalculates all calculated cells in the given row. The calculations are performed from left to right, first column to last column.

qddb_tablerowmaxnum
returns the number of rows in the given table.

qddb_tablerowgetval
returns a list containing the cell values for the specified row.

qddb_tablerowsetval
accepts a list containing the cell values for the specified row. The list must contain the same number of elements as the number of columns in the table.

qddb_tablerowcget
retrieves the current value of the given row option. Available row options are:

-comment

- a general comment for the row

-name

- a symbolic name for the row; must be of the form "[a-zA-Z][a-zA-Z0-9._-]*"

-title

- a title for the row -variable - an array variable that can be used for direct access to cell values in the row, using the column name as the index

qddb_tablerowconfigure
sets the row option to the given value. Multiple options may be given in a single command.

qddb_tablecolinsert
appends one new column to the table by default. If the -before option is given, then the column is inserted before the given column. If the -numcols option is given, the given number of columns are inserted or appended to the table. The default number of columns is one.

qddb_tablecoldelete
deletes the given column from the table.

qddb_tablecolclear
clears the given column of all values and options, leaving the column intact. All options and values are cleared and reset to the defaults.

qddb_tablecolcopy
copies the given column and places the copy in the specified location. If the destination ('to') column exists, it is overwritten; if it doesn't exist, it is created. The source ('from') column must exist or an error is returned.

qddb_tablecoleval
recalculates all calculated cells in the given column. The calculations are performed from top to bottom, first row to last row.

qddb_tablecolmaxnum
returns the number of columns in the given table.

qddb_tablecolgetval
returns a list containing the unformatted cell values of the given column.

qddb_tablecolsetval
accepts a list containing the cell values for the specified column. The list must contain the same number of elements as the number of columns in the table.

qddb_tablecolcget
retrieves the current value of the given row option. Available row options are:

-comment

- a general comment for the column

-name

- a symbolic name for the column; must be of the form "[a-zA-Z][a-zA-Z0-9._-]*"

-title

- a title for the column -variable - an array variable that can be used for direct access to cell values in the column, using the column name as the index

-type

- the default type of the given column (string, real, integer, date, or calc)

-justify

- the default justification of the column for output purposes; may be one of `left', `right' `center', or `none'. The `none' option provides no padding between separators.

-width

- the default width of the column for output purposes -precision - the default precision (to the right of the decimal) of the column if the column is of type real -separator - the default separator to append to the column for printing purposes (default: space)

qddb_tablecolconfigure
sets the value of the given option to the given value (see above). Multiple options may be given in a single command.

qddb_tablecellcopy
copies the given cell's values and options to the provided destination. Both source (from) and destination (to) cells must exist or an error is returned. The value of the name option is not copied.

qddb_tablecelleval
recalculates the given calculated cell.

qddb_tablecellgetval
returns the unformatted value of the given cell.

qddb_tablecellsetval
sets the given cell to the specified value. The value should be of the appropriate type.

qddb_tablecellcget
returns the current value of the specified option for the given cell. The available options are the same as those available for columns plus the following:

-calc

- formula for calculating the field if the cell is type `calc'; if the field is not type `calc', an error is returned.

qddb_tablecellconfigure
sets the value of the specified option to the given value. If the option is `-calc' and the type of the cell is not type `calc', then the field is redefined as a calculated field and its value set to zero before evaluating the calculated expression.

qddb_table provides calculated fields for spreadsheetstyle operations. Calculated fields have the type calc and any value assigned to the field is automatically calculated based on the provided expression.

You can also evaluate arbitrary expressions that are not associated with a particular cell or table with qddb_tableexpr. You must provide an explicit table argument to any range functions (or to each range).

There are four types of subexpressions: numeric constants/expressions, ranges, range functions, and numeric
functions. Ranges can only be used as arguments to a range function. Range functions take ranges as arguments and produce real numbers; numeric functions take numbers as arguments and produce real numbers.

The optional tablename may be either the explicit name of a table, or the table descriptor returned by qddb_tabledefine. Each range must have an associated table, either explicit or implicit. qddb_tableexpr has no implicit table, so all range functions (see below) or ranges must specify a table explicitly. When a range function has a table argument, all ranges used as arguments to that function have an implicit table. Implicit tables do not propagate to subexpressions used within arguments to range functions.

Row and column names may be used as arguments to ranges, as well as numeric expressions and the following constants: @thisrow, @thiscol, @maxrow, and @maxcol. The constants are evaluated in the current table context (that is, the calculated field's implicit table).

Each range produces a list of cells to be evaluated by a range function. @range produces a list of all cells in the rectangular region specified by the four numeric arguments (row,col:row,col). Ranges have no meaning by themselves and must be used as arguments to a range function. Cell and cell ranges (@range and @cell) may be abbreviated with just `@'.

Rangefunctions
A range function accepts a list of ranges separated by commas and produces a numeric result. The result of a range function is a numeric value that can be used in any expression, or as the argument to a numeric function. All range functions have the form

Numericfunctions
A numeric function accepts numeric values as arguments and produces a numeric result. No table context is required for numeric functions. The numeric functions accept any numeric expression as an argument.

computes sqrt(e1*e1 + e2*e2) in such a way that underflow will not happen

Logicalexpressions
A logical expression performs various logical operations and returns the numeric value 1.0 if true, and 0.0 if false. Logical operations may be fully parenthesized.

=

equal to

<

less than

<=

less than or equal to

>

greater than

>=

greater than or equal to

!=

not equal to

&

logical and

|

logical or

!

logical not (unary)

Logical expressions are used as the first argument to the @if function. If the logical expression is true, then @if evaluates to the second argument. If the logical expression is false, it evaluates to the third argument.

Tables produced by qddb_rows(n) contain row and/or tuple descriptors in their row comment fields; these should be explicitly deleted from memory before deleting the table. Failure to do so will result in a memory leak.

When setting an expression for a calculated field containing a reference to a non-existent table, the calculation is delayed until the table exists.