The SET command is used to modify a table item. The following sub-commands are valid for all table types, unless otherwise specified.
for simple tables
SET table index|* entryValue [ /Tag|Untag ]
for extended tables
SET table index|* fieldId fieldValue [ … ] [ /Tag|Untag ] [ /N=n|all|tagged ]
Assign a value to an entry or append a new entry to the table. To append an entry to the end of the table use an asterisk instead of index. If index is greater than the number of entries (table), empty entries are added between the last entry and the new entry. The options /Tag or /Untag can be used to set or clear the tag flag. Note: If only one argument is supplied for extended tables the field separator character can be used to separate fields in the string entryValue. This means entryValue is parsed in the same way as entries are loaded from files. You can set multiple entries at the same time using the option /N.
The zero-based index of an existing entry to modify the entry's data ir a zero-based index greater than the number of existing entries, to add a new entry. If the index is greater than nEntries+1, then all missing entries are created and initialized with default values. An asterisk can be used to append the table with a new entry at the next free index.
The value to assign to the entry.
A valid field id (as defined in the NEW TABLE command) or a field index.
The value to assign.
Repeat this assignment for the next 'n' entries (/N=n), or for all entries from the current one to the last one (/N=all), or for all tagged entries from the current on 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
This command is only applicable to extended tables
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).
The name or index of the field to be configured / updated.
Show (1|ON) or hide (0|OFF) field in listbox and list view controls
Show name and value (1|ON) or only value (0|OFF) in list box controls. Only active if show is ON.
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).
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.
Enable (1|ON) or disable (0|OFF) missing value replacement. Missing value replacement is disabled by default. If enabled, missing values are replaced by msym.
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).
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.
The text to be displayed in the field's column header of a listview control.
The width (in characters) of the column of a listview control.
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)
Enable (1) or disable (0) the sort function of the column header of a listview control.
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.
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.
The field id specifying the field in listtable where the values are stored. If listtable is a simple table, listfield must be 0.
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.
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.
If set to ON or 1, the last user-input for this field will be used as the respective default value.
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.
There are three ways to copy the contents of one table to another. The first is when creating a table (#t := new table * $#baseTable /Copy /All), the second if using the following syntax: $#table1 := $#table2, and the third is the following command:
SET table COPY srctable [fieldid ... ] [ /Rows /Columns ]
Copy data between two tables - the source table (srcTable) and the target table (table). If fields (fieldids) are specified, then only these fields are copied. Otherwise all of the source table's fields are copied. If the command is called without options (/R|C), then the source table must have the same fields as the target table and the source entries overwrite the target entries (appending entries if necessary).
The options /Rows and /Columns do not overwrite existing entries and fields in the target table. Rather they modify the 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 not defined yet).
Note that both tables must be extended or parameter tables.
The id of source table to copy from. This must be an extended or parameter table.
A blank separated list of field ids. If specified, these fields are copied, otherwise all fields are copied.
If specified, entries 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).
If specified, entries from srctable are copied to the same entries in table. Fields not defined in table are automatically defined and configured. For this reason there must be enough undefined fields in table.
SET table COPY outputName i j [ /Row|Col ] [ /Write ]
The name of a value item to copy to or from.
The entry index.
The field index.
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.
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.
If the option /Write is specified, the table data is copied to the value item, otherwise (default) the value item data is copied to the table.
SET table CLIPBOARD [ /Show|Write ]
Copy the visible entries of a table to the clipboard. The entries can be copied in the show-format (/Show; use listbox display format (default)) or in the write-format (/Write; use the format for writing to files). You can specify the write and show format using the SET table CONFIG command.
Use the show format to format each entry string. This is the default.
Use the write format to format each entry string.
SET table CLIPBOARD /Read [ /Delete ] [ /Empty ]
Read the last entry from the clipboard. Reading is only successful if the format is supported. The formats CF_UNICODETEXT and CF_TEXT are supported.
Delete the table entries before reading from the clipboard.
Empty the clipboard after a successful read.
This command is only applicable to extended tables
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 index of the field to be defined or '*' for the next free index.
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.
The name to assign to the field. Note that this must also be a valid name.
The number of fields to define. Used in conjunction with offset for multiple definitions. Must be >= 1.
The index to start multiple definitions with. Must be >= 0.
SET table DEFINE index|name [... /Undefine]
Undefine an existing field and delete contents of all field entries. If the option /Undefine is used in conjunction with multiple parameters, multiple undefines are possible.
The index or name of the field(s) to undefine.
SET table DEFINE fieldName newName /R
Rename an existing field.
The existing field name.
The new field name
The mandatory option /R, specifying that this DEFINE command should rename the field.
An example can be found in the macro file table_redefine.sts.
SET table [index] /Delete
Delete all visible entries or the specified entry index.
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 command 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 commands), the tagged entries are those matching the FIND 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.
The expression defining one search criterion (see Find expressions for details).
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
Initialize a new find cycle (this is like a call to FIND without arguments and is applied before query).
Invert all tag flags (applied after query).
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
Check if a value is (not) assigned to a field.
Check the value of a numerical field (type INTEGER or NUMBER) or find an absolute string match (type STRING for == and !=).
Match the value of a string field (type NAME or STRING).
This command 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.
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.
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"
delimiter string used to separate the fieldindex from the fieldvalue (for format 1 only)
Float format string used for all fields of type NUMBER. This can be any valid C string format specifier.
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.
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.
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.
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.
If specified, TRYLOCK will try to get a lock once per millisecond until it is either successful, or timeout milliseconds have elapsed.
If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
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.
"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
SET table UNLOCK
Unlock table access.
This command is only applicable to extended tables
SET table MODE mode [access format decimal]
Set table mode (configuration / data) and general attributes.
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.
This argument is currently meaningless. It is reserved for future database functions and should be set to '0' or '*'.
Selects the format to be used for file I/O: 0=show format, 1=write (default) format.
Sets the character to be used as the decimal symbol. By default, the period '.' is used.
Since S_TOOLS-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.
SET table /All|Tagged
Make all table entries visible (/A) or only tagged entries visible (/T).
Only visible entries can be accessed, deleted or displayed (e.g. in a list box).
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.
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.