Catalogue Command (ODBC Only)
Returns meta data about columns in a table.
columns DATABASE SCHEMA TABLE
DATABASE
The catalogue or database name that includes the table to be processed.
SCHEMA
The schema or table owner of the table to be processed.
TABLE
The table name of the table to be processed.
Description
Use this command to obtain information about the columns within a table. The application must have been logged into a data source using the login command, otherwise the following error message will be displayed:
Error: Not connected to database
Certain database management systems do not support different "Database" (or Catalogue) or "Schema" (or Table Owner), if so, a null string needs to be passed as the first and/or second parameter using the syntax '' (i.e. two single quotes).
If the parameters are valid, a result set will be returned, one row per column in the specified table.Each row contains a number of fields, the actual number may increase, dependent of the ODBC version, but will always start with the following:
Column name |
Column Number |
Comment |
TABLE_CAT |
1 |
Catalog name (aka. Database Name); can be Null if not applicable to the data source. |
TABLE_SCHEM |
2 |
Schema name (aka. Table Owner); can be Null if not applicable to the data source. |
TABLE_NAME |
3 |
Table name. |
COLUMN_NAME |
4 |
Column name: can be an empty string ("") for a column that does not have a name. |
DATA_TYPE |
5 |
SQL data type. This can be an ODBC SQL data type or a driver-specific SQL data type. See Microsoft ODBC document for a list of data types. |
TYPE_NAME |
6 |
Data source–dependent data type name; for example, "CHAR", "VARCHAR", "MONEY", "LONG VARBINAR", or "CHAR ( ) FOR BIT DATA". |
COLUMN_SIZE |
7 |
If DATA_TYPE is SQL_CHAR or SQL_VARCHAR, this column contains the maximum length in characters of the column. For datetime data types, this is the total number of characters required to display the value when converted to characters. For numeric data types, this is either the total number of digits or the total number of bits allowed in the column, according to the NUM_PREC_RADIX column. |
BUFFER_LENGTH |
8 |
The length in bytes of data transferred on a SELECT statement. For numeric data, this size may be different than the size of the data stored on the data source. This value might be different than COLUMN_SIZE column for character data. |
DECIMAL_DIGITS |
9 |
The total number of significant digits to the right of the decimal point. Will be Null for data types where DECIMAL_DIGITS is not applicable. |
NUM_PREC_RADIX |
10 |
For numeric data types, either 10 or 2. If it is 10, the values in COLUMN_SIZE and DECIMAL_DIGITS give the number of decimal digits allowed for the column. For example, a DECIMAL(12,5) column would return a NUM_PREC_RADIX of 10, a COLUMN_SIZE of 12, and a DECIMAL_DIGITS of 5; a FLOAT column could return a NUM_PREC_RADIX of 10, a COLUMN_SIZE of 15, and a DECIMAL_DIGITS of NULL. If it is 2, the values in COLUMN_SIZE and DECIMAL_DIGITS give the number of bits allowed in the column. For example, a FLOAT column could return a RADIX of 2, a COLUMN_SIZE of 53, and a DECIMAL_DIGITS of NULL. Will be Null for data types where NUM_PREC_RADIX is not applicable. |
NULLABLE |
11 |
SQL_NO_NULLS (i.e. "0") if the column could not include NULL values. SQL_NULLABLE (i.e. "1") if the column accepts NULL values. SQL_NULLABLE_UNKNOWN (i.e. "2") if it is not known whether the column accepts NULL values. The value returned for this column is different from the value returned for the IS_NULLABLE column. The NULLABLE column indicates with certainty that a column can accept NULLs, but cannot indicate with certainty that a column does not accept NULLs. The IS_NULLABLE column indicates with certainty that a column cannot accept NULLs, but cannot indicate with certainty that a column accepts NULLs. |
REMARKS |
12 |
A description of the column. |
COLUMN_DEF |
13 |
The default value of the column. |
SQL_DATA_TYPE |
14 |
SQL data type, as it appears in the SQL_DESC_TYPE record field in the IRD. This can be an ODBC SQL data type or a driver-specific SQL data type. This column is the same as the DATA_TYPE column, with the exception of datetime and interval data types. |
SQL_DATETIME_SUB |
15 |
The subtype code for datetime and interval data types. For other data types, this column returns a Null. |
CHAR_OCTET_LENGTH |
16 |
The maximum length in bytes of a character or binary data type column. For all other data types, this column returns Null. |
ORDINAL_POSITION |
17 |
The ordinal position of the column in the table. The first column in the table is number 1. |
IS_NULLABLE |
18 |
"NO" if the column does not include NULLs. "YES" if the column could include NULLs. This column returns an empty string ("") if nullability is unknown. |
If the parameters are invalid, then an error message "ERROR: Failed to obtain column information" will be returned.
Example
subroutine GetColumnList(string: TableOwner_SV, string: TableName_SV, string: ColumnList_SV) is
string ColumnName_LSV
copy "" to ColumnList_SV
begin guarded
response to start
send "columns '' " TableOwner_SV " " TableName_SV "\n" to SQL
response to "SQL>" from SQL
leave block
response to line from SQL
extract from input
skip by "~" # Catalog
skip by "~" # Schema
skip by "~" # Table
take to "~" ColumnName_LSV
append ColumnName_LSV "\n" to ColumnList_SV
end