SET TABLE

Table Item
INTRODUCTION	NEW	SET	ATTRIBUTES

The SET table… command is used to modify a table item. The sub-commands documented here are valid for all table types, unless otherwise specified.

Setting or Adding table entries

SET table index|* … [ /Tag | /Untag ]

When using the index of an existing entry for index, the command will modify the respective entry. When supplying the asterisk, "*", for index, a new entry will be appended to the end of the table. Finally, when supplying a value for index that is greater than the number of entries (table[]), the table will be padded with an appropriate number of empty entries in order to allow the entry index to be set.

The options /Tag and /Untag may be used for setting or clearing the tag flag.

Remember that with STx table indexes are always zero-based.

Unstructured adding

SET table index|* entryValue [ /Tag|Untag ]

This statement is the sole way of adding entries to a simple table. The statement is applicable to extended tables, too. With extended tables, the field separator character may be used to separate fields in the string entryValue, meaning that entryValue will be parsed in the same way as entries are loaded from files.

`index`	The zero-based index of an existing entry to modify the entry's data or a zero-based index greater than the number of existing entries, to add a new entry. If the index is greater than the total number of entries, then all missing entries are created and initialized with default values. An asterisk may be used to append the table with a new entry at the next free index.
`entryValue`	The value to assign to the entry.
`/Tag` or `/Untag`	tag, or untag, the respective entry

Adding structured data to extended tables

SET table index|* fieldId₁ fieldValue₁ [ … fieldId_n fieldValue_n ] [ /Tag|Untag ] [ /N=n|all|tagged ]

The structured variant of setting entries allows to address the fields of an entry. It is thus applicable to extended tables only. Using the option /N, you may even set multiple entries at the same time.

`index`	The zero-based index of an existing entry to modify the entry's data or a zero-based index greater than the number of existing entries, to add a new entry. If the index is greater than the total number of entries, then all missing entries are created and initialized with default values. An asterisk may be used to append the table with a new entry at the next free index.
`fieldId₁`…	A valid field id (as defined in the `NEW TABLE` command) or a field index.
`fieldValue₁`…	The value to assign to the respective field.
`/Tag` or `/Untag`	tag, or untag, the respective entry
`/N=n`	Repeat this assignment for the next `n` entries (with `/N=n` and `n` being an integer higher than, or equal to, 1), or for all entries from the current one to the last one (with `/N=all`), or for all tagged entries from the current one to the last one (`/N=tagged`). Note that the `all` and `tagged` variants cannot append new entries to the table. Note also that you cannot set 'all' entries, if only tagged entries are currently visible.

// initialize the first field of the first 10 entries with the value 0.
$#extTable 0 0 0 /N=10

Retrieving a table entry

You can retrieve a table entry using the following syntax: $#table[$#index]. If the table has columns defined, you can use the syntax $#table[$#index,$#columnid].

Configuring a table field

The SET table CONFIG command is only applicable to extended tables (after all, simple tables do not have fields).

SET table CONFIG fieldid [ show name scale format mmode mval msym header width align sort editable
                         [ listtable listfield listonly setdefault setuserdefault multirow ] ]

Configure a table field. Define the display format (list box and list view) and field properties. The field must have been specified in the NEW TABLE command. The table must be in configuration mode (see MODE).

`fieldid`	The name or index of the field to be configured / updated.
`show`	Show (`1` or `ON`) or hide (`0` or `OFF`) the field in listbox and list view controls
`name`	Show both name and value (`1` or `ON`) or value only (`0` or `OFF`) in list box controls. This is only effective if `show` is `ON`.
`scale`	The scaling factor for numeric fields; if a numeric field is accessed in the show format, its value is multiplied with scale (used by both listboxes and listviews).
`format`	The show format format string. For fields of type `NAME` or `STRING`, the format must contain a string tag (e.g.: `%s`, `%10.10s`) For both numeric field types (`INTEGER` and `NUMBER`), the format must contain a float tag (`%f`, `%g`). The float tag is necessary for integer values because the scaling factor (`scale`) is a floating number. Note that to display an integer (without decimals) you can use the format tag `%5.0f`. This parameter controls the format for listboxes and listviews dialog controls.
`mmode`	`ON`) or disable (`0`\|`OFF`) missing value replacement. Missing value replacement is disabled by default. If enabled, missing values are replaced by `msym`.
`mval`	The numeric id value of a 'missing value' (e.g. `0` for f0 data). The default is `0`. Missing value replacement only works for numerical fields (`NUMBER` or `INTEGER`).
`msym`	The replacement symbol (string) for missing values (e.g. `UNVOICED` for f0 data). The strings `<empty>` and `<blank>` can be used to replace a missing value with an empty string or a blank character. The default string is the empty string.
`header`	The text to be displayed in the field's column header of a listview control.
`width`	The width (in characters) of the column of a listview control.
`align`	Align field left (`0`) or right (`1`) in the column of a listview control; The first column of a listview is always. left-aligned (align is ignored)
`sort`	Enable (`1`) or disable (`0`) the sort function of the column header of a listview control.
`editable`	If `editable` is set to `0`, the respective field (column) of the table is NOT editable when the table is connected to a `ListView` item. If `editable` is set to a number different from `0`, the respective field (column) of the table IS editable when the table is connected to a `ListView` item. See the example script `editabletable.sts` for a complete example.
`listtable`	The name of a table containing all permissible values for this field. If this table (`table`) is connected to a `listview` item, and the `listtable` parameter is specified, the `listview` displays a combobox in the associated column, and fills the combobox with `listtable`'s values.
`listfield`	The field id specifying the field in `listtable` where the values are stored. If `listtable` is a simple table, `listfield` must be `0`.
`listonly`	The `listonly` parameter specifies whether this `table`'s field may only use values in the list table (`1`), or whether any values may be entered (`0`). If `0`, then the combobox is editable.
`setdefault`	The `setdefault` parameter specifies whether invalid or empty data entered whilst editing should be replaced by the default value (`1`=yes, `0`=no). The first value in the list table is the default value.
`setuserdefault`	If set to `ON` or `1`, the last user-input for this field will be used as the respective default value.
`multirow`	If set to `1` or `ON`, the field can display text in multiple rows. If set to `0` or `OFF`, text will be displayed in one row. The default is `OFF`.

A field is defined once, but can be configured as often as needed. If an argument is not supplied or set to '*', the configuration for that parameter is not changed.See the example script editabletable.sts for a detailed example.

Table-to-table Copy

SET table COPY srctable [fieldid … ] [ /Rows /Columns ]

Copy data from the source table srcTable (a parameter table or an extended table) to the target table table (a table of the same kind). If fields (fieldids) are specified, then only these fields are copied. Otherwise all fields of the source table are copied.

If the command is called without supplying options /Rows or /Columns), then

the source table must have the same format, i.e. the same fields, as the target table; and
the source entries will overwrite the target entries (appending entries if necessary).

If the command is called with either option /Rows or /Columns, the command will not overwrite existing entries and fields in the target table. Rather than that, the command will modify the target table, appending source fields (which do not exist in the target table) and entries to the target table. Note that the target table must have enough undefined fields to accommodate the appended fields (i.e. fields created by NEW TABLE, but yet undefined).

Note that the COPY command works only with extended and with parameter tables.

srctable: The table to copy from. This must be an extended or parameter table.
fieldid: An optional list of field IDs, separated by blank. If specified, only these fields are copied. If omitted, all fields are copied.
/Rows: If specified, fields from srctable are appended to table. The fields being copied must already be defined in table. Note that the field data type is not checked (i.e. number fields can be copied to string fields of the same name).
/Columns: If specified, entries from srctable are copied to the same entries in table, overwriting their old value. Fields not defined in table are automatically defined and configured. For this reason there must be enough undefined fields in table.

Copying between a Table and a Value Item

SET table COPY outputName i j [ /Row|Col ] [ /Write ]

Copy data between a table and a value object. If the option /Write is used, the table data is copied to the value item, otherwise (default) the value item data is copied to the table.

outputName: The name of a value item to copy to or from.
i: The entry index.
j: The field index.
/Row: Copy table fields starting at row i field j. The number of fields copied is determined by the size of the vector. The number of rows copied is determined by the number of vectors (only for array value items). This option is only for array and vector value items.
/Col: Copy table entries starting at row i, field j. The number of rows copied is determined by the size of the vector. The number of fields copied is determined by the number of vectors (array value items). This option is only for array and vector value items.
/Write: If the option /Write is specified, the table data is copied to the value item. If omitted, the value item data is copied to the table.

Copying to and from the clipboard

SET table CLIPBOARD [ /Show|Write ]

Copy the visible entries of a table to the clipboard. The entries can be copied either in:

show-format, i.e. using listbox display format, when supplying the /Show option (or no option at all, since this is the default); or in
write-format, i.e. the format normally used when writing to a file. This is done with the /Write option.

/Show: Use the show format to format each entry string. This is the default.
/Write: Use the write format to format each entry string.

SET table CLIPBOARD /Args arg1 arg2 ... [ /Show|Write ]

Copy the content of the arguments to the clipboard. Each argument argI can be a string (string is copied) or a table item (content of table is copied). The option /Show|Write specifies the output format used for the table items (as described above). The content of the table item table is only copied, if it is specified as argument.

SET table CLIPBOARD /Read [ /Delete ] [ /Empty ]

Read the last entry from the clipboard. This will work only if the format of the respective clipboard entry is either Unicode (CF_UNICODETEXT) or text (CF_TEXT).

/Read: Mandatory option.
/Delete: Delete the table entries before reading from the clipboard.
/Empty: Empty the clipboard after a successful read.

Defining a table field

SET table DEFINE index|* type name [count offset] [/Auto] [/Undefine]

Note that the table must be in configuration mode (see MODE). Define the data type and name of field index (0 .. number of fields - 1). If an asterisk '*' is given instead of index, the first free (undefined) index is used. The argument type is the id of the data type of the field. The argument name is the name to be assigned to the field and must be a valid name string. The parameters count and offset can be used to define multiple fields with one command (count = number of fields, offset = base index). The option /Auto ensures the name is unique by concatenating the string name with an index (first value: 1). Note that once you have configured the table, you need to switch to DATA mode (see MODE below).

The SET table DEFINE command is only applicable to extended tables, since only they support different types of fields.

index: The index of the field to be defined or '*' for the next free index.
type: The type of data to be stored. The following values are supported:; NAME - Strings which are valid names.; STRING - Free text.; INTEGER - Integer numbers.; NUMBER - Floating point numbers.
name: The name to assign to the field. Note that this must also be a valid name.
count: The number of fields to define. Used in conjunction with offset for multiple definitions. Must be >= 1.
offset: The index to start multiple definitions with. Must be >= 0.

Undefining a table field

SET table DEFINE index|name [… /Undefine]

Undefine an existing field and delete contents of all field entries. Multiple undefines are possible by using the option /Undefine in conjunction with multiple parameters.

index|name: The index or name of the field(s) to undefine.

Renaming a table field

SET table DEFINE fieldName newName /Rename

Rename an existing field.

fieldName: The existing field name.
newName: The new field name
/R: The mandatory option /Rename, specifying that this DEFINE command should rename the field.

An example can be found in the macro file table_redefine.sts.

Deleting table entries

SET table [index] /Delete

Delete all visible entries or the specified entry index.

Finding table entries

The FIND function implements a simple 'database query' interface for tables. To create complex queries, it may be necessary to apply a set of FINDs and possibly combine them with the FIND command. The FIND function only searches tagged entries. Therefore, if you want to search the whole table, you must tag all the entries first. At the end of a query (any number of FIND function calls), the tagged entries are those matching the search criteria.

SET table FIND

Initialize a new find cycle. The tag flag of all entries are set and visibility is set to ALL. This command should be issued before a new query consisting of multiple commands is started. Instead of this command the option /Start can be used with the (first) FIND.

SET table FIND cexpr [loper cexpr ...] [/Start /Invert /Tagged]

Search for all tagged entries matching the criteria defined by the cexpr and loper arguments. The tag flags of all not matching entries are cleared. The logical operators are evaluated strictly from left to right. This means the result of all expressions of the left side of an operator is combined with the result of the expression on the right side. The logical operators AND (=&&), OR (=||) and XOR (=^^) are defined. Note that the field value for simple tables is 0.

cexpr

The expression defining one search criterion (see Find expressions for details).

loper

The logical operator combining two search criteria; logical operators are applied from left to right, bracketing is not possible. The following operators are supported:

conjunction: AND or &&

disjunction: OR or ||

exclusive disjunction: XOR or ^^

/Start

Initialize a new find cycle (this is like a call to FIND without arguments and is applied before query).

/Invert

Invert all tag flags (applied after query).

/Tagged

Switch to visibility "tagged" (applied after query).

// search for entries where key field ends with 'ing'
// and show only tagged entries
$#t find 'key:=I:*ing' /Tagged

Find expressions

`cexpr`	Description
`fieldid:cond`
`fieldid`	name or index of a defined field
`cond`	`=` (is assigned), `!` (is not assigned)

`fieldid:cond:value`
`fieldid`	name or index of a numerical field (`0` for simple tables)
`cond`	`<`, `<=`, `==`, `!=`, `>=` or `>`
`value`	a number or numerical expression, or a string.

`fieldid:cond:mask`

`fieldid`	name or index of a string field (`0` for simple tables)
`cond`	`=I`	match, ignoring case
	`!I`	do not match, ignoring case
	`=R`	match, respecting case
	`!R`	do not match, respecting case
`mask`	match string, may contain wildcard characters. if `field` is of type `name`, mask must be a valid name

Regular expressions

S_TOOLS-STx supports searches using POSIX regular expression. When using regular expressions, characters which have a special meaning in STx will need to be escaped using the STx escape character "`".

fieldid:cond:regex

fieldid	name or index of a string field (`0` for simple tables)
cond	=RI	matching regular expression ignoring case
	=RR	matching regular expression respecting case
	!RI	not matching regular expression even if ignoring case
	!RR	not matching regular expression if respecting case.
regex	a POSIX regular expression.

The script regular_expressions.sts provides examples of usage.

Formatting table fields

Formatting is only applicable to extended tables.

SET table FORMAT format [listdel vardel numfmt  intfmt]

Configuration of the write format used to save and load tables from files (see SET file LOAD and SET file SAVE). You can configure the show format (used to display tables in the GUI) using the CONFIG command.

format: 0 - Store all fields even if they are empty. Assigned fields have the format fieldvalue listdel and empty fields have just the listdel. E.g.: 10.0 ; 10.1 ; ; 10.3

1 - Only assigned fields are stored. Every assigned field outputs the following string fieldindex vardel fieldvalue listdel. E.g.: c0=10.0 ; c1=10.1 ; c2= ; c3=10.3

Note: In order to load a table successfully, it must be loaded using the same format setting as was used to save it.

listdel: delimiter string used to separate fields in the output line (for both formats). The special symbol '%t' can be used to specify the tab character. Consecutive white spaces (blanks and tabs) are interpreted as one delimiter. E.g. " 1 2 3" is interpreted as three fields, whereas ":1::2:3"

vardel: delimiter string used to separate the fieldindex from the fieldvalue (for format 1 only)

numfmt: Float format string used for all fields of type NUMBER. This can be any valid C string format specifier.

intfmt

Integer (!) format string used for all fields of type INTEGER. This can be any valid C string format specifier.

You can set the decimal symbol using the MODE command.

///////////////////////////////////////////////////////////////////////////////
//
//    Macro:          load_a_file_into_a_table.sts
//    Description:    load the contents of a numeric text file into a parameter
//                    table and displays the table if desired
//    Parameters:     #fileName    the file to load
//                    #mode        0    silent
//                                 1    show table
//                                 2    return table
//    Return:         0 on success, non-zero on failure
//    Usage:          load_a_file_into_a_table [file] ; [show]
//    Author:         Jonnie White
//    History:        2005-03-31    jw    created
//                    2005-04-27    jw    added new mode (return table) and file 
//                                        parameter
//
///////////////////////////////////////////////////////////////////////////////
[macro load_a_file_into_a_table]
    #fileName := set '$scriptDirectory\input_matrix_small.txt'
    #mode := 1
    readvar #argv #fileName';'#mode

    // create a parameter table with 4 fields
    #tableItem := new table * 4 /Parameter number:f:4
    if '$#tableItem' == * em -1 ; failed to create a table
    
    // set the write format to blank separated
    $#tableItem format 0 ' '
    
    // create the read-only file object associated with fileName
    #fileItem := new file * '$#fileName' /Text /Read
    if '$#fileItem' == * em -1 ; failed to open the file $#fileName
    
    // load the file into the table
    $#fileItem load $#tableItem
    if '$rc' > 0 em -1 ; failed to load file $#fileName into table $#tableItem
    
    // show the table
    if '$#mode' == 1 showitem $#tableItem
    
    // return table
    if '$#mode' == 2 then
        delete $#fileItem
        exit 1 set '$#tableItem'
    else
        // clean up
        delete $#fileItem $#tableItem
    end
exit 1 int 0

Note that if you need to save a table containing empty fields, you should *not* use a blank or a tab character as the delimiter. If you do, the empty fields will be omitted on loading the table.

Locking / Unlocking the table

The use of lock/unlock is only important, if a table item is (or may be) used by more than one thread. In STx shells, spu items and display item are running in their own thread.

SET table LOCK [/Save]

Lock the table item. The execution of the calling shell is stopped, until the item can be locked. If locked, only the shell which locked it has access to the item until it is explicitly unlocked with the command UNLOCK. Always beware of deadlocks.

SET table LOCK timeout [Save]

Try to lock the table item, but wait only the specified time. This command returns 0 (success) if the lock request was successful within the timeout, and a non-zero error code if not. If the caller already holds the lock, the command will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting. The argument timeout specifies the maximum lock-timeout in milliseconds and must be a number greater than zero.

If the table is locked with the option /Save, the tag state of each entry, the current order and the mode is saved on lock and restored with the unlock command. In this case in the critical section entries can only be modified, but not created or deleted.

SET table UNLOCK

Unlock the table item. Note: It's very important that for each successful LOCK, an UNLOCK is called!

See lock_example.sts in the script examples directory for an example.

Setting the table mode

This command is only applicable for extended tables.

SET table MODE mode [access format decimal]

Set table mode (configuration / data) and general attributes.

mode

A flag to switch the table mode to configuration mode (0) or data mode (1); After creating an extended table the table may be in configuration or data mode, depending on the NEW command. See NEW table for details.

access

This argument is currently meaningless. It is reserved for future database functions and should be set to '0' or '*'.

format

Selects the format to be used for file I/O: 0…show format, 1…write (default) format.

decimal

Sets the character to be used as the decimal symbol. By default, the period '.' is used.

Since STx 3.7.0, the NEW TABLE syntax has been modified to include the field definitions. The table mode is then automatically set to data, and hence this command may in future be pretty much obsolete, except for setting the decimal symbol.

Showing and hiding table entries

SET table /All|Tagged

Make either all table entries visible (/All) or only tagged entries (/Tagged).

Only visible entries can be accessed, deleted or displayed (e.g. in a list box).

Sorting table entries

SET table SORT [/Respect]

Invert entry order (all tables)

For simple tables:

SET table SORT dir [/Respect]

For extended tables:

SET table SORT fieldid dir […] [/Respect]

Sort table entries. For simple tables only the sort direction (dir: Ascending (0), Descending (1)) can be selected.

For extended tables, one or more fields and the sort direction can be specified. The sort function ignores the visibility setting and sorts all table entries. If the option /Respect is used, strings are sorted respecting their case, otherwise the sort is case-insensitive.

Tagging table entries

SET table /Reset|Invert

Reset (/Reset) or invert (/Invert) tag flags of all entries and set visibility to ALL.

SET table index /Tag|Untag|Invert

Set, clear or invert tag flag of an entry. These options can also be used in all table commands assigning a value.

The command TAGS can be used to save and restore a table's tagged entries.