Programmer Guide/Shell Items/Table/TABLE Item Attributes

Table Item
INTRODUCTION	NEW	SET	ATTRIBUTES

Table attributes

Generally, table attributes, and table entries, are retrieved in the following way:

#target := $#table[…]

Overview

$#table[!ATTRIBUTE]	retrieves the respective attribute ATTRIBUTE; see below for the list of available attributes.
$#table[]	retrieves the number of entries in a table (bluntly put: its size)
$#table[$#index, $#fieldid]	This expression will return the value of field fieldid (named by its index, or by its name) of entry index (a number in the range 0…$#table[]-1).
$#table[$#index, !TAGGED]	this 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.

List of attributes

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
	0	otherwise
!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 !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 Also see the example script editabletable.sts for a complete example.
!EXTENDED	1	if table is an extended table
	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 format type name show showname scale format [mvalue msymbol]. Here the respective fields have the following meanings:
	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, msymbol	missing value and symbol
	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 may be found here: Field Attributes
!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 hugo, the expression will evaluate to 1 if the table has at least one column. If the table is completely devoid of columns, the expression evaluates to zero.
!ICOLUNDEFINED	currently undocumented
!INTFORMAT	C format string for integer fields. Must be a valid format for one integer number.
	Note:	the values of the attributes !IO, !LSEP, !VSEP, !NUMFORMAT and !INTFORMAT may be modified with the command SET table FORMAT.
!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 may be modified with the command SET table FORMAT.
!LSEP	the list separator string, used to separates, as its name implies, fields
	Note:	the values of the attributes !IO, !LSEP, !VSEP, !NUMFORMAT and !INTFORMAT may be modified with the command SET table FORMAT.
!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.
!NCOLUNDEFINED	the number of undefined 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.
	Note:	the values of the attributes !IO, !LSEP, !VSEP, !NUMFORMAT and !INTFORMAT may be modified with the command SET table FORMAT.
!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.
!TAGGED	The number of tagged entries.
!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.
	Note:	the values of the attributes !IO, !LSEP, !VSEP, !NUMFORMAT and !INTFORMAT may be modified with the command SET table FORMAT.

Field Attributes

These attributes can be queried for any defined fields in an extended table:

NAME, TYPE, VISIBLE, SCALE, FORMAT, MMODE, MVALUE, MSYMBOL, HEADER, WIDTH, ALIGN, SORTABLE, EDITABLE, VTABLE, VFIELD, VONLY, VDEFAULT, VUSERDEFAULT