Skip to content
≡

Administrator

Developer

Tools

External Tools

SQLDescribeCol

SQLDescribeCol#

SQLDescribeCol returns the name of the column, data type, decimal value, and NULLability of columns from the result set.

SQLDescribeColW() as a Unicode string supports same execution as SQLDescribeCol().

Syntax#

SQLRETURN SQLDescribeCol (
    SQLHSTMT        stmt,
    SQLSMALLINT         col,
    SQLCHAR *       name,
    SQLSMALLINT         nameMax,
    SQLSMALLINT *       nameLength,
    SQLSMALLINT *       type,
    SQLINTEGER *        precision,
    SQLSMALLINT *       scale,
    SQLSMALLINT *       nullable );

Arguments#

Data Type Argument In/Output Description
SQLHSTMT stmt Input Statement handle
SQLSMALLINT col Input Order of the parameter marker. Starts with 1
SQLCHAR* name Output Pointer of the column name
SQLSMALLINT nameMax Input The character number of the *Name
SQLSMALLINT * nameLength Output The length of the *name (excluding NULL-termination byte)
SQLSMALLINT * type Output Pointer of the SQL data type in the column
SQLINTEGER * precision Output Pointer of column size in databaseThe Altibase CLI driver returns 0 ,when pointer column size cannot be decided
SQLSMALLINT * scale Output Pointer of the number of decimal values in databaseIf the number of decimal values in the database cannot be decided or is not proper, the Altibase CLI driver will return 0.
SQLSMALLINT * nullable Output The pointer of the value that indicates whether the column allows NULL.
SQL_NO_NULLS: The column does not allow NULL data.
SQL_NULLABLE: The column allows NULL data

Return Values#

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR

Description#

An application usually calls SQLPrepare(), and calls SQLDescribeCol() before SQLExecute(). An application can call also SQLDescribeCol() after calling SQLExecDirect().

SQLDescribeCol() searches names, types, and lengths of the columns created by SELECT statements. If the column is an expression, *name will be also an expression.

Diagnosis#

SQLSTATE Description Comments
01004 String data, right-truncated If the buffer name is not long enough to return the entire column name, the length of the full column name will be returned as nameLength.
07009 Invalid descriptor index The col value is 0. The identified col value is higher than the number of columns in the result set.
HY000 General error
HY090 Invalid string or buffer length The identified nameMax is smaller than 0.

If SQLDescribeCol() is called after SQLPrepare() and before SQLExecute(), all SQLSTATE that can be returned by SQLPrepare() or SQLExecute() can be returned.

SQLBindCol
SQLColAttribute
SQLFetch
SQLNumResultCols
SQLPrepare

Example#

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

sprintf(query,"SELECT * FROM DEMO_EX1");
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++ )
{
    SQLDescribeCol(stmt, i+1,
                   (SQLCHAR *)columnName, sizeof(columnName), &columnNameLength,
                   &dataType, &columnSize, &scale, &nullable);
    printf("columnName = %s, nullable = %d\n", columnName, nullable);
}