TABLE Item Attributes
There are attributes of a shell item as a whole, and attributes peculiar to a field (i.e., column) of a table. We like to call the former table attributes, and the letter field attributes.
Table attributes
Shell table attributes may be retrieved using the following syntax:
#value := $#table[!ATTRIBUTE]
You may retrieve the number of entries in a table using the following syntax:
#nEntries := $#table[]
Each table entry can also be queried as follows:
$#table[$#index, $#fieldid]
The above expression will return the value of field fieldid (named by its index, or by its name) of entry index (number).
$#table[$#index, !TAGGED]
The above expression evaluates to 1 if entry index is tagged, and to 0 otherwise.
$#table[$#index]
For a simple table, this expression returns the entry at the respective index. For extended tables, the return value depends on the mode: for extended tables in data-access mode, the value of all fields of the respective entry are returned, the result depending on the selected format (SHOW or WRITE); for extended tables in configuration mode, the expression will return the configuration of the field referenced by index (index being the numerical index, or the name, of the desired field). The format of the result is the same as for attribute !FIELD.
In addition, the following attributes are available:
| Attribute | Value(s) and Description | |
|---|---|---|
| !CHUNKSZ | The number of entries per memory chunk used for growing the table when the allocated memory runs out. This is the value passed to NEW table with the option /N=m.
| |
| !DIRECTORY | 1 if table is a segment directory and 0 if not
| |
| !EDITABLE | The item attribute !EDITABLE indicates whether the respective field (column) of the table is editable when the table is connected to an STx dialog item listview control. You may both query the !EDITABLE attribute, and assign to it. By assigning to the !EDITABLE attribute of a column, you may at any time specify if the respective column may be edited by the user: Assigning 0 prevents editing, whereas any numeric value different from 0 allows for editing.
The E.g. An optional third argument can be used to specify number of fields to set (if omitted, just the one field Examples: // query if the 3rd column of table #tab is editable #txt := COND $#tab[!edit,2] == 0 ? 'is NOT' : 'IS' um 'Column 2 (i.e. 3rd column) $#txt editable.' // allow for the 3rd column (index 2) of table #tab to be edited $#tab[!edit,2] := 1 // prevent its first column (index 0) from being edited $#tab[!edit,0] := 0 // set the 2nd and 3rd columns to editable $#tab[!edit,1,2] := 1 Also see the example script | |
| !EXTENDED | 1 if table is an extended table and 0 otherwise.
| |
| !FIELDS | The !FIELDS attribute returns the number of defined fields (note that this is the same as !NCOL).
If specified with a field name or index (e.g. | |
| type | numeric type id (0=undefined, 1=NAME, 2=STRING, 3=INTEGER, 4=NUMBER) | |
name
|
field name | |
show
|
1 if field is included in show format | |
showname
|
1 if name is included in show format | |
scale
|
show scaling factor for numeric types | |
format
|
format string used for show | |
mvalue,
|
missing value and symbol | |
| If the field does not exist, an empty string is returned.
If a field attribute is also specified (e.g. | ||
| !HASFIELD | $#table[!hasfield,hugo] evaluates to 1 in case of table #table having a field (i.e. column) called "hugo" (for arbitrary values of "hugo"). It evaluates to 0 otherwise.
If you do not supply a | |
| !INTFORMAT | C format string for integer fields. Must be a valid format for one integer number. | |
| !IO | The index of selected I/O format (0 or 1): | |
| 0 | all fields of an entry are stored; fields are separated by the list separator (!LSEP) | |
| 1 | the index and the value of assigned fields are stored; index and value are separated by the value-separator (!VSEP) and fields are separated by the list-separator (!LSEP). | |
| Note: | the values of the attributes !IO, !LSEP, !VSEP, !NUMFORMAT and !INTFORMAT can be modified with the command SET table FORMAT
| |
| !LSEP | the list separator string, used to separates, as its name implies, fields | |
| !MEMORY | returns the size of the pre-allocated memory in bytes and the amount of memory currently being used in bytes in the format reserved used.
This attribute is currently supported by extended, and parameter tables only (-1 is returned for other table types). | |
| !NCOL | the number of columns | |
| !NROW | the number of rows (note that this is the same as the !FIELDS attribute)
| |
| !NUMFORMAT | the C format string for numeric fields. This must be a valid format for one float number. | |
| !PARAMETER | 1 | if the table is a parameter table |
| 0 | otherwise | |
| !RANGED | 1 | if only tagged entries are visible |
| 0 | if all entries are visible | |
| !SHELL | ID of the shell creating the table item (8 digit hexadecimal number) | |
| !SORT | The table sort mode in the following format:
C F1 O1 F2 O2 F3 O3… | |
C
|
is 0 or 1, indicating whether sorting is case-insensitive (0), or case-sensitive (1) | |
F1
|
the field number of the primary sort field (the primary key) | |
O1
|
indicates the sort order for the primary key, 0 indicating ascending order, and 1 indicating descending order | |
F2 O2
|
are the field number, and the sort order for the secondary key, and so on. | |
There will be as many Fn On pairs as there are sort keys.
| ||
If the table is unsorted, the !SORT attribute will be empty which, when you think about it, seems quite the right thing for it to be in this case.
| ||
| !STARTZ | The number of entries allocated on initialization. This is the value passed to the /I=n option of the NEW table command.
| |
| !USERS | number of linked items using the respective table item. | |
| !VSEP | The value-separator string, used to separate the field name from the field value. | |
Field Attributes
Table field attributes may be queried using the following syntax:
$#table[!FIELD,$#fieldid,attribute]
The following attributes are available:
| Attribute | Value(s) and Description | |
|---|---|---|
| ALIGN | 0
|
if the text field is aligned to the left |
1
|
if the text field is aligned to the right | |
| EDITABLE | 1
|
if this field is editable |
0
|
otherwise. | |
| FORMAT | returns the field's so-called show format string (as set using the SET table CONFIG fieldid command, q.v.).
| |
| HEADER | the field's text header, displayed at the top of the column in an attached listview.
| |
- MMODE
1 if missing value replacement is enabled, 0 otherwise.
- MSYMBOL
The symbol used to represent missing values in a listview.
- MULTIROW
The table field attribute !MULTIROW can be used to query and set the "multirow" property of a table row. If set to '1', the table field will support multirow entries.
- MVALUE
The numerical value of a values to be recognised as 'missing'.
- NAME
Returns the name (id) of the field.
- SCALE
The value numerical fields are multiplied with when displayed in the show format. See SET table CONFIG for details.
- SORTABLE
1 if clicking the associated column in a listview will sort the column, or 0 to disable column sorting.
- TYPE
Returns the field type: INT|NUM|STRING|NAME
- VDEFAULT
Returns the value list default value, if defined.
- VFIELD
Returns the index of the value field in the value list table (if specified). See the table item command CONFIG for details).
- VISIBLE
1 if the field is visible in an attached listview, 0 if it is hidden.
- VONLY
1 if only values in the associated value table are permissible, 0 otherwise.
- VTABLE
The name of the value list table (if specified). See SET table CONFIG for details.
- VUSERDEFAULT
The table field attribute VUSERDEFAULT returns the 1 if the SET table CONFIG parameter setuserdefault was set to ON for this field.
- WIDTH
Returns the width of the column in characters (this value is used by an associated listview).
