Documentation for our re-implemented and
improved
ns_column for AOLserver 3.0 and later
ns_column
Overview
Find information about columns of tables in the database
Syntax
ns_column count dbhandle table
ns_column exists dbhandle table column
ns_column list dbhandle table
ns_column name dbhandle table colindex
ns_column type dbhandle table column ?typeLengthVar?
ns_column typebyindex dbhandle table colindex ?typeLengthVar?
ns_column value dbhandle table [column | * ] key
ns_column valuebyindex dbhandle table colindex key
ns_columnnotnull dbhandle table column
ns_columncomputed dbhandle table column
ns_columndata dbhandle table [column | * ] key
Description
Each of these functions requires a database handle for the dbhandle argument and a table name for the table argument. Use ns_db gethandle to get a database handle.
ns_column count returns the number of columns in the specified table.
ns_column exists returns 1 (one) if the specified column exists in the specified table and 0 (zero) if it does not.
ns_column list returns a Tcl list of columns in the specified table in their order in the database. This option is new in version 3.0.
ns_column name returns the name of the column specified by the zero-based column index (colindex) in the specified table. If colindex is not a valid index (i.e. not an integer or too large) and error will be thrown.
ns_column type returns the type of the specified column (e.g., integer, varchar). If typeLengthVar is specified, a variable of this name is set with the precision / length of the datatype. I.e. for varchar(25), it will be set to 25; for integer to its precision (typically 10). The optional variable name is new in version 3.0.
ns_column typebyindex returns the type of the column specified by the zero-based column index (colindex). If typeLengthVar is specified, a variable of this name is set with the precision / length of the datatype. I.e. for varchar(25), it will be set to 25; for integer to its precision (typically 10). The optional variable name is new in version 3.0. If colindex is not a valid index (i.e. not an integer or too large) and error will be thrown.
ns_column value returns the value of the column attribute specified by key. If column is *, returns an unordered column-value list of lists (keyed list) for the specified key. This is only valid for ExtendedTableInfo operations. * support is new in version 3.0.
ns_column valuebyindex returns the value of the column attribute specified by key. This function is the same as ns_column value except that the column must be specified by the zero-based column index (colindex). If colindex is not a valid index (i.e. not an integer or too large) and error will be thrown.
Additional information on key in ns_column value/valuebyindex
ns_column retrieves metadata information about columns in a given table. There are two types of metadata information: system (i.e. as stored in the database server's system tables based on the create/alter table DDL statements executed for this table); extended (i.e. table customization data stored in the ns2_columns table - this must be enabled for this pool with the ExtendedTableInfo (TclExtendedTableInfo in version 3.0) boolean configuration parameter). ns_column type/typebyindex always retrieve system metadata. ns_column value/valuebyindex retrieve both types depending on the key according to the table below:
| key | Metadata Type | Description |
|---|---|---|
| type | System | This is equivalent to ns_column type only without support for datatype length variable. |
| not_null | System | Returns 1 (one) if column cannot have a null value and 0 (zero) otherwise (t or f for Illustra). |
| is_computed | System | Returns 1 (one) if column is a computed column and 0 (zero) if it is a regular column. Attempts to insert into or update a computed column will typically cause a database exception. This key is new in version 3.0. |
| unique | Extended | If the table was created through the Database Services Administration page with the Add New Table button, this will return 1 (one) or t if column was specified as unique and 0 (zero) or f otherwise. |
| default | Extended | Returns the default value for this column as set under Database Services Administration |
| order | Extended | Returns the order index for this column as set under Database Services Administration |
| description | Extended | Returns the description for this column as set under Database Services Administration |
| htmltag_type | Extended | Returns the input type for this column as set under Database Services Administration |
| htmltag_data | Extended | Returns the input type configuration data for this column as set under Database Services Administration |
| displayas | Extended | Returns the display type for this column as set under Database Services Administration |
| display_type_data | Extended | Returns the display type configuration data for this column as set under Database Services Administration |
| htmltag_attrs | Extended | Returns a string of the HTML attributes for this column as set under Database Services Administration. This option can be used to specify HTML attributes of the input widget. It can also be used to configure the given widget or trigger javascript events using custom attributes. |
ns_column returns a null string if the information requested is not available, which can happen if Extended Metadata is disabled or the database does not support the particular system metadata attribute or if it is undefined or if the table does not exist.
Version 3.0 adds the following commands which are used internally by ns_column but can also be called directly:
ns_columnnotnull is equivalent to ns_column value dbhandle table column not_null
ns_columncomputed is equivalent to ns_column value dbhandle table column is_computed
ns_columndata is equivalent to ns_column value dbhandle table column key but only for Extended Metadata key types.
