TABLE Item Attributes

Shell table attributes can be retrieved using the following syntax:

#value := $#table[!ATTRIBUTE]

You can 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]

Returns the value of field fieldid (number or field name) of entry index (number)

$#table[$#index, !TAGGED]

Returns 1 if entry index is tagged and 0 if not

$#table[$#index]

Returns the value of table entry at this index in simple tables. For extended tables the return value depends on the mode: for extended tables in data-access mode, the value of all fields of the referenced entry are returned; the result depends on selected format (SHOW or WRITE); for extended tables in configuration mode, the configuration of the field index (number or field name). The format of the result is the same as for attribute !FIELD.

In addition, the following attributes are available:

!CHUNKSZ

The number of entries per memory chunk used when 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 S_TOOLS-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 !EDITABLE attribute has the index of the respective column as its mandatory second argument.

E.g. $#table[!editable,$#iField]

An optional third argument can be used to specify number of fields to set (if omitted, just the one field #iField is set).

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

See the example script editabletable.sts for a complete example.

!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. $#table[!FIELDS,$#fieldId]), then the configuration for that field is returned in the following format:

type name show showname scale format [mvalue msymbol]

Where the above values have the following meanings:

If the field does not exist, an empty string is returned.

If a field attribute is also specified (e.g. $#table[!FIELDS,$#fieldId,!ATTRIBUTE]), then the field's attribute value is returned. A list of field attributes are can be found here: Field Attributes

!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):

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 fields.

!MEMORY

Returns the size of the pre-allocated memory in bytes and the amount of memory currently being used in bytes in the following format:

reserved used

This attribute is currently only supported by extended and parameter tables (-1 is returned by other table types).

!NCOL

The number of columns

!NROW

The number of rows ((Note that this is the same as !FIELDS).

!NUMFORMAT

The C-format string for numeric fields. This must be a valid format for one float number.

!PARAMETER

1 if table is a parameter table (numeric fields only) and 0 if not

!RANGED

1 if only tagged entries are visible and 0 if all entries are visible

!SHELL

Id of the shell creating the table item (8 digit hex number)

!SORT

The table sort mode in the following format:

C F1 O1 F2 O2 F3 O3 ...

where C is 0 or 1 indicating that sorting is case-insensitive (0) or case-sensitive1;

where F1 is the field number of the first sort field (the "main key"), and O1 indicates whether for this key the table will be sorted in ascending order (0) or in descending order(1); where F2/O2 is the field number and the sort order for the second sort 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.

!STARTZ

The number of entries allocated on initialization. This is the value passed to NEW table with the option /I=n.

!USERS

Number of linked items using the table item.

!VSEP

The value-separator string, used to separate the field name from the field value.