Programmer Guide/Shell Items/Table/SET TABLE

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|* fieldId1 fieldValue1 [ … fieldIdn fieldValuen ] [ /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.
fieldId1…	A valid field id (as defined in the NEW TABLE command) or a field index.
fieldValue1…	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.

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

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

1. the source table must have the same format, i.e. the same fields, as the target table; and
2. 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 fro the clipboard

SET table CLIPBOARD [ /Show|Write ]

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

1. 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
2. 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 /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:

AND - conjunction

&& - conjunction OR - disjunction || - disjunction XOR - exclusive disjunction

^^ - exclusive disjunction

/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

Table items can be locked to prevent access by shells other than the locking shell.

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

LOCK

SET table LOCK [/Save]

Lock table access. If a table is locked, only the shell which locked it has access to its content. The table must be unlocked after finishing the 'critical' processing section.

During the execution of most table commands, the table is automatically locked temporarily to the shell (by the table command). The table is also locked temporarily to a dialog during update processes. If the table is locked with the option /Save, the tag flags and the current order and 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.

TRYLOCK

SET table TRYLOCK [ timeout ] [ /S ]

Try to lock the table item table. If no timeout is specified, TRYLOCK returns immediately. If the caller already *holds* the lock, TRYLOCK will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting.

timeout

If specified, TRYLOCK will try to get a lock once per millisecond until it is either successful, or timeout milliseconds have elapsed.

/S

If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

Return Codes:

0 - an unlocked table has been successfully locked. 381 - Error: if the table could not be locked due to it being locked by someone else. 382 - Warning: identical to 381, except that this returned when the /S flag is specified. 383 - Error: if the table could not be locked due to it being locked by the caller. 384 - Warning: identical to 383, except that this returned when the /S flag is specified.

Example:

"SET $#table TRYLOCK 5000" will try hard to lock the table. If it does not succeed within 5000ms (i.e., five seconds), it will fail - but it will not fail earlier.

The TRYLOCK command is intended for safe multithreading without race conditions occurring

UNLOCK

SET table UNLOCK

Unlock table access.

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.