SQLColAttribute

SQLColAttribute#

SQLColAttribute brings the attributes for the column of the result set, and judges the count of columns.

SQLColAttributeW() as a Unicode string supports same execution as SQLColAttribute().

Syntax#

SQLRETURN  SQLColAttribute (
    SQLHSTMT        stmt,
    SQLSMALLINT         columnNumber,
    SQLSMALLINT         fieldIdentifier,
    SQLCHAR *       charAttributePtr,
    SQLSMALLINT     bufferLength,
    SQLSMALLINT *       stringLengthPtr,
    SQLPOINTER*     numericAttributePtr );

Arguments#

Data Type	Argument	In/Output	Description
SQLHSTMT	stmt	Input	Statement handle
SQLSMALLINT	columnNumber	Input	The column position in the result set. Starts with 1.
SQLSMALLINT	fieldIdentifier	Input	Information identifier to know: SQL_DESC_CASE_SENSITIVE, SQL_DESC_CATALOG_NAME, SQL_DESC_COUNT, SQL_DESC_DISPLAY_SIZE, SQL_DESC_LABEL, SQL_DESC_LENGTH, SQL_DESC_NAME, SQL_DESC_NULLABLE, SQL_DESC_PRECISION, SQL_DESC_SCALE, SQL_DESC_SCHEMA_NAME, SQL_DESC_TABLE_NAME, SQL_DESC_TYPE, SQL_DESC_TYPE_NAME, SQL_DESC_UNSIGNED
SQLCHAR *	charAttributePtr	Output	Buffer pointer to store data to be returned when fieldIdentifier in columnNumber is the character string. If field value is an integer, it is not used.
SQLSMALLINT	bufferLength	Input	The character number of charAttributePtrIf charAttributePtr is an integer, this field is ignored.
SQLSMALLINT *	stringLengthPtr	Output	Pointer to a buffer in whih to return the total number of bytes (excluding the null-termination byte) available to return in charAttributePtr.
SQLPOINTER*	numericAttributePtr	Output	Pointer of the integer buffer to which the value of fieldIdentifier field in columnNumber row is returned.

Return Values#

SQL_SUCCESS
SQL_INVALID_HANDLE
SQL_ERROR

Description#

Instead of returning a specified arguments set such as SQLDescribeCol(),using SQLColAttribute() the attributes for a specified column can be defined. In case the required information is a string type, it will be returned to charAttributePtr. In case the required information is numeric type, it will be returned to numericAttributePtr.

The column is identified by its position (from left to the right, starting with 1).

Call SQLNumResultCols() before calling SQLColAttribute() to check whether the result set exists.

SQLDescribeCol() must be called before SQLBindCol() in case an application does not know about column attributes such as data types, length, etc.

fieldIdentifier Descriptor Types#

The following table shows the descriptor types returned by SQLColAttribute().

Descriptor (fieldIdentifier)	Data Type	Description
SQL_DESC_AUTO_UNIQUE_VALUE	SQLINTEGER	Whether the type of the column is auto increment data SQL_TRUE: Increase SQL_FALSE: Not available
SQL_DESC_BASE_COLUMN_NAME	SQLCHAR *	The default column name of the result set column
SQL_DESC_BASE_TABLE_NAME	SQLCHAR *	The name of the base table that contains the column
SQL_DESC_CASE_SENSITIVE	SQLINTEGER	The discrimination of upper and lower characters
SQL_DESC_CATALOG_NAME	SQLCHAR *	The catalog of the table including columns
SQL_DESC_CONCISE_TYPE	SQLINTEGER	Concise data type. datetime and interval data types return a concise form
SQL_DESC_COUNT	SQLINTEGER	The column number of the result set is returned.
SQL_DESC_DISPLAY_SIZE	SQLINTEGER	The maximum number of characters to display the column data
SQL_DESC_FIXED_PREC_SCALE	SQLLEN	Whether the column contains a different fixed precision and nonzero scale for each data source SQL_TRUE: include SQL_FALSE: not included
SQL_DESC_LABEL	SQLCHAR *	The label of the column. If there is no label, the column name is returned. If there is no label and the column name is returned, an empty string is returned.
SQL_DESC_LENGTH	SQLINTEGER	The maximum value of column string or binary data type or length of actual string
SQL_DESC_LITERAL_PREFIX	SQLCHAR *	Prefix characters recognized when using this data type as a literal
SQL_DESC_LITERAL_SUFFIX	SQLCHAR *	Suffix characters recognized when using the data type as a literal
SQL_DESC_LOCAL_TYPE_NAME	SQLCHAR *	Localized (national) names for data types
SQL_DESC_NAME	SQLCHAR *	The name of the column
SQL_DESC_NULLABLE	SQLINTEGER	Whether the column can contain NULL SQL_NULLABLE: can contain NULL SQL_NO_NULLS: cannot contain NULL SQL_NULLABLE_UNKNOWN: Unknown
SQL_DESC_OCTET_LENGTH	SQLLEN	The length of the string or binary data type in bytes
SQL_DESC_PRECISION	SQLINTEGER	Precision attribute of the column
SQL_DESC_SCALE	SQLINTEGER	Decimal point attributes of the column
SQL_DESC_SCHEMA_NAME	SQLCHAR *	Schema of the table including the columns
SQL_DESC_SEARCHABLE	SQLINTEGER	SQL_PRED_NONE: The column is not available in the WHERE clause (equivalent to SQL_UNSEARCHABLE in ODBC 2.x) SQL_PRED_CHAR: If the column can only use the LIKE condition in the WHERE clause (equivalent to SQL_LIKE_ONLY in ODBC 2.x) SQL_PRED_BASIC: The column can be used with any comparison operator except the LIKE condition in the WHERE clause (equivalent to SQL_EXCEPT_LIKE in ODBC 2.x) SQL_PRED_SEARCHABLE: the column can be used with all comparison operators in the WHERE clause
SQL_DESC_TABLE_NAME	SQLCHAR *	Table Name
SQL_DESC_TYPE	SQLINTEGER	SQL data type
SQL_DESC_TYPE_NAME	SQLCHAR *	Database type name
SQL_DESC_UNNAMED	SQLINTEGER	SQL_NAMED: if the column name or column alias exists SQL_UNNAMED: if the column name or column alias does not exist
SQL_DESC_UNSIGNED	SQLINTEGER	Inspection of column items
SQL_DESC_UPDATABLE	SQLINTEGER	Returns whether the data in the result set column is updatable. SQL_ATTR_READONLY: read only SQL_ATTR_WRITE: Read-Write SQL_ATTR_READWRITE_UNKNOWN: Unknown if updateable

Diagnosis#

SQLSTATE	Description	Comments
07009	Invalid column number	columnNumber is 0 or higher than the number of columns in the result set
HY000	General error

SQLBindCol
SQLDescribeCol  
SQLFetch

Example#

< Refer to: $ALTIBASE_HOME/sample/SQLCLI/demo_meta8.cpp >

sprintf(query,"SELECT * FROM DEMO_META8");
if (SQLExecDirect(stmt, (SQLCHAR *)query, SQL_NTS) != SQL_SUCCESS)
{
    execute_err(dbc, stmt, query);
    SQLFreeStmt(stmt, SQL_DROP);
    return SQL_ERROR;
}

SQLNumResultCols(stmt, &columnCount);

for ( i=0; i<columnCount; i++ )
{
    SQLColAttribute(stmt, i+1,
                    SQL_DESC_NAME,
                    columnName, sizeof(columnName), &columnNameLength,
                    NULL);
    SQLColAttribute(stmt, i+1,
                    SQL_DESC_TYPE,
                    NULL, 0, NULL,
                    &dataType);
    if (dataType == SQL_NUMERIC)
    {
        SQLColAttribute(stmt, i+1,
                        SQL_DESC_PRECISION,
                        NULL, 0, NULL,
                        &precision);
    }
    else
    {
        SQLColAttribute(stmt, i+1,
                        SQL_DESC_LENGTH,
                        NULL, 0, NULL,
                        &columnSize);
    }
    SQLColAttribute(stmt, i+1,
                    SQL_DESC_SCALE,
                    NULL, 0, NULL,
                    &scale);
    SQLColAttribute(stmt, i+1,
                    SQL_DESC_NULLABLE,
                    NULL, 0, NULL,
                    &nullable);
}

Administrator

Reference

Developer

Tools

External Tools

SQLColAttribute