Please enable JavaScript to view this site.

ESL Documentation

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