SQLColAttribute 関数

準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: ISO 92

まとめ
SQLColAttribute は、結果セット内の列の記述子情報を返します。 記述子情報は、文字列、記述子に依存する値、または整数値として返されます。

構文

  
SQLRETURN SQLColAttribute (  
      SQLHSTMT        StatementHandle,  
      SQLUSMALLINT    ColumnNumber,  
      SQLUSMALLINT    FieldIdentifier,  
      SQLPOINTER      CharacterAttributePtr,  
      SQLSMALLINT     BufferLength,  
      SQLSMALLINT *   StringLengthPtr,  
      SQLLEN *        NumericAttributePtr);  

引数

StatementHandle
[入力]ステートメント ハンドル。

ColumnNumber
[入力]フィールド値の取得元となる IRD 内のレコードの番号。 この引数は、1 から始まる列の順序で順番に並べ替えられた結果データの列数に対応します。 列は任意の順序で記述できます。

この引数では列 0 を指定できますが、SQL_DESC_TYPEとSQL_DESC_OCTET_LENGTHを除くすべての値は未定義の値を返します。

FieldIdentifier
[入力]記述子ハンドル。 このハンドルは、IRD のどのフィールドにクエリを実行するかを定義します (たとえば、SQL_COLUMN_TABLE_NAME)。

CharacterAttributePtr
[出力]フィールドが文字列の場合、IRD の ColumnNumber 行の FieldIdentifier フィールドの値を返すバッファーへのポインター。 それ以外の場合、フィールドは使用されません。

CharacterAttributePtr が NULL の場合、StringLengthPtr は引き続き、CharacterAttributePtr が指すバッファーで返すことができる合計バイト数 (文字データの null 終端文字を除く) を返します。

BufferLength
[入力] FieldIdentifier が ODBC で定義されたフィールドで、 CharacterAttributePtr が文字列またはバイナリ バッファーを指している場合、この引数は *CharacterAttributePtr の長さである必要があります。 FieldIdentifier が ODBC 定義フィールドで、*CharacterAttributePtr が整数の場合、このフィールドは無視されます。 *CharacterAttributePtr が Unicode 文字列の場合 (SQLColAttributeW を呼び出すとき)、引数BufferLengthは偶数である必要があります。 FieldIdentifierがドライバー定義フィールドの場合、アプリケーションは、BufferLength 引数を設定することによって、ドライバー マネージャーにフィールドの性質を示します。 BufferLength には、次の値を指定できます。

• CharacterAttributePtr がポインターへのポインターである場合、BufferLength は値をSQL_IS_POINTERする必要があります。

• CharacterAttributePtr が文字列へのポインターである場合、BufferLength はバッファーの長さです。

• CharacterAttributePtr がバイナリ バッファーへのポインターである場合、アプリケーションは SQL_LEN_BINARY_ATTR(length) マクロの結果を BufferLength に配置します。 これにより、 BufferLength に負の値が設定されます。

• CharacterAttributePtr が固定長データ型へのポインターである場合、BufferLength は、SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT、またはSQL_IS_USMALLINTのいずれかである必要があります。

StringLengthPtr
[出力]*CharacterAttributePtr で返すことができる合計バイト数 (文字データの null 終了バイトを除く) を返すバッファーへのポインター。

文字データの場合、返されるバイト数が BufferLength 以上の場合、*CharacterAttributePtr 内の記述子情報は BufferLength に切り捨てられ null 終端文字の長さを差し引いた値に切り捨てられ、ドライバーによって null で終了されます。

他のすべての種類のデータでは、 BufferLength の値は無視され、ドライバーは *CharacterAttributePtr のサイズが 32 ビットであると見なします。

NumericAttributePtr
[出力]フィールドが SQL_DESC_COLUMN_LENGTH などの数値記述子型の場合、IRD の ColumnNumber 行の FieldIdentifier フィールドの値を返す整数バッファーへのポインター。 それ以外の場合、フィールドは使用されません。 一部のドライバーでは、下位の 32 ビットまたは 16 ビットのバッファーのみを書き込み、上位ビットを変更しない場合があることに注意してください。 そのため、アプリケーションでは、この関数を呼び出す前に値を 0 に初期化する必要があります。

返品

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

SQLColAttributeがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、HandleType SQL_HANDLE_STMT のSQLGetDiagRec を呼び出し、Handle StatementHandle を指定します。 次の表に、 SQLColAttribute によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

SQLPrepare後とSQLExecuteより前に呼び出された場合、SQLColAttribute は、データ ソースが StatementHandle に関連付けられている SQL ステートメントを評価するタイミングに応じて、SQLPrepare または SQLExecute から返すことができる任意の SQLSTATE を返すことができます。

パフォーマンス上の理由から、アプリケーションはステートメントを実行する前に SQLColAttribute を呼び出さないでください。

Comments

アプリケーションが SQLColAttributeによって返される情報をどのように使用するかについては、「 Result Set Metadata」を参照してください。

SQLColAttribute は、*NumericAttributePtr または *CharacterAttributePtr で情報を返します。 整数情報は、*NumericAttributePtr で SQLLEN 値として返されます。その他のすべての形式の情報は *CharacterAttributePtr で返されます。 *NumericAttributePtr で情報が返されると、ドライバーは CharacterAttributePtr、 BufferLength、および StringLengthPtr を無視します。 *CharacterAttributePtr で情報が返されると、ドライバーは NumericAttributePtrを無視します。

SQLColAttribute は IRD の記述子フィールドから値を返します。 この関数は、記述子ハンドルではなくステートメント ハンドルを使用して呼び出されます。 このセクションで後述する FieldIdentifier の SQLColAttribute によって返される値はSQLGetDescFieldを適切な IRD ハンドルで呼び出すことによっても取得できます。

現在定義されている記述子フィールド、そのフィールドが導入された ODBC のバージョン、およびそれらの情報が返される引数については、このセクションの後半で説明します。異なるデータ ソースを利用するために、ドライバーによって定義される記述子の種類が増える可能性があります。

ODBC 3.x ドライバーは、各記述子フィールドの値を返す必要があります。 記述子フィールドがドライバーまたはデータ ソースに適用されず、特に明記されていない限り、ドライバーは *StringLengthPtr または *CharacterAttributePtr の空の文字列を返します。

旧バージョンとの互換性

ODBC 3.x 関数 SQLColAttribute は非推奨の ODBC 2. を置き換えますx 関数 SQLColAttributes。 SQLColAttributesをSQLColAttribute にマッピングする場合 (ODBC 2.x アプリケーションは ODBC 3. で動作していますx ドライバー)、またはSQLColAttributeをSQLColAttributes にマッピングする (ODBC 3. の場合)x アプリケーションは ODBC 2. で動作していますx ドライバー) ドライバー マネージャーは、FieldIdentifier の値を渡すか新しい値にマップするか、次のようにエラーを返します。

• ODBC 2. の#define値x FieldIdentifier は ODBC 3. の#define値と同じですx FieldIdentifier 関数呼び出しの値が渡されるだけです。

• ODBC 2. の#define値x FieldIdentifiers SQL_COLUMN_LENGTH、SQL_COLUMN_PRECISION、およびSQL_COLUMN_SCALEは ODBC 3. の#define値とは異なりますx FieldIdentifiers SQL_DESC_PRECISION、SQL_DESC_SCALE、およびSQL_DESC_LENGTH。 ODBC 2.x ドライバーは ODBC 2. のみをサポートする必要がありますx 値。 ODBC 3.x ドライバーは、これら 3 つの FieldIdentifiers の "SQL_COLUMN" と "SQL_DESC" の両方の値をサポートする必要があります。 ODBC 3. では有効桁数、小数点以下桁数、長さが異なるため、これらの値は異なります。x ODBC 2. よりもx。 詳細については、「 列サイズ、10 進数、転送オクテットの長さ、および表示サイズを参照してください。

• ODBC 2. の#define値x FieldIdentifier は ODBC 3. の#define値とは異なりますx FieldIdentifier COUNT、NAME、および NULLABLE 値で発生すると、関数呼び出しの値が対応する値にマップされます。 たとえば、SQL_COLUMN_COUNTはSQL_DESC_COUNTにマップされ、マッピングの方向に応じてSQL_DESC_COUNTがSQL_COLUMN_COUNTにマップされます。

• FieldIdentifier が ODBC 3. の新しい値である場合x:ODBC 2. に対応する値がありませんでしたx、ODBC 3. の場合はマップされません。x アプリケーションは、ODBC 2. の SQLColAttribute の呼び出しでそれを使用しますx ドライバーを呼び出すと、SQLSTATE HY091 (無効な記述子フィールド識別子) が返されます。

次の表に、 SQLColAttribute によって返される記述子の型を示します。 NumericAttributePtr 値の型はSQLLEN *です。

SQLColAttribute は、 SQLDescribeCol の拡張可能な代替手段です。 SQLDescribeCol は、ANSI-89 SQL に基づく記述子情報の固定セットを返します。 SQLColAttribute では、ANSI SQL-92 および DBMS ベンダー拡張機能で使用できる、より広範な記述子情報にアクセスできます。

関連する関数

例

次のサンプル コードでは、ハンドルと接続は解放されません。 ハンドルとステートメントを解放するコード サンプルについては、「 SQLFreeHandle 関数、 Sample ODBC Program、および SQLFreeStmt 関数 を参照してください。

// SQLColAttibute.cpp  
// compile with: user32.lib odbc32.lib  
  
#define UNICODE  
  
#include <windows.h>  
#include <sqlext.h>  
#include <strsafe.h>  
  
struct DataBinding {  
   SQLSMALLINT TargetType;  
   SQLPOINTER TargetValuePtr;  
   SQLINTEGER BufferLength;  
   SQLLEN StrLen_or_Ind;  
};  
  
void printStatementResult(SQLHSTMT hstmt) {  
   int bufferSize = 1024, i;  
   SQLRETURN retCode;  
   SQLSMALLINT numColumn = 0, bufferLenUsed;
   
   retCode = SQLNumResultCols(hstmt, &numColumn);  
   
   SQLPOINTER* columnLabels = (SQLPOINTER *)malloc( numColumn * sizeof(SQLPOINTER*) );  
   struct DataBinding* columnData = (struct DataBinding*)malloc( numColumn * sizeof(struct DataBinding) );  
  
   printf( "Columns from that table:\n" );  
   for ( i = 0 ; i < numColumn ; i++ ) {  
      columnLabels[i] = (SQLPOINTER)malloc( bufferSize*sizeof(char) );  
  
      retCode = SQLColAttribute(hstmt, (SQLUSMALLINT)i + 1, SQL_DESC_LABEL, columnLabels[i], (SQLSMALLINT)bufferSize, &bufferLenUsed, NULL);  
      wprintf( L"Column %d: %s\n", i, (wchar_t*)columnLabels[i] );  
   }  
  
   // allocate memory for the binding  
   for ( i = 0 ; i < numColumn ; i++ ) {  
      columnData[i].TargetType = SQL_C_CHAR;  
      columnData[i].BufferLength = (bufferSize+1);  
      columnData[i].TargetValuePtr = malloc( sizeof(unsigned char)*columnData[i].BufferLength );  
   }  
  
   // setup the binding   
   for ( i = 0 ; i < numColumn ; i++ ) {  
      retCode = SQLBindCol(hstmt, (SQLUSMALLINT)i + 1, columnData[i].TargetType,   
         columnData[i].TargetValuePtr, columnData[i].BufferLength, &(columnData[i].StrLen_or_Ind));  
   }  
  
   printf( "Data from that table:\n" );  
   // fetch the data and print out the data  
   for ( retCode = SQLFetch(hstmt) ; retCode == SQL_SUCCESS || retCode == SQL_SUCCESS_WITH_INFO ; retCode = SQLFetch(hstmt) ) {  
      int j;  
      for ( j = 0 ; j < numColumn ; j++ )  
         wprintf( L"%s: %hs\n", columnLabels[j], columnData[j].TargetValuePtr );  
      printf( "\n" );  
   }  
   printf( "\n" );   
}  
  
int main() {  
   int bufferSize = 1024, i, count = 1, numCols = 5;  
   wchar_t firstTableName[1024], * dbName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize ), * userName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize );  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLWCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen, bufferLen;  
   SQLRETURN retCode;  
  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   struct DataBinding* catalogResult = (struct DataBinding*) malloc( numCols * sizeof(struct DataBinding) );  
   SQLWCHAR* selectAllQuery = (SQLWCHAR *)malloc( sizeof(SQLWCHAR) * bufferSize );  
  
   // connect to database  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLCHAR *)(void*)SQL_OV_ODBC3, -1);  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
   retCode = SQLDriverConnect(hdbc, desktopHandle, L"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1025, &connStrBufferLen, SQL_DRIVER_PROMPT);  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   // display the database information  
   retCode = SQLGetInfo(hdbc, SQL_DATABASE_NAME, dbName, (SQLSMALLINT)bufferSize, (SQLSMALLINT *)&bufferLen);  
   retCode = SQLGetInfo(hdbc, SQL_USER_NAME, userName, (SQLSMALLINT)bufferSize, &bufferLen);  
  
   for ( i = 0 ; i < numCols ; i++ ) {  
      catalogResult[i].TargetType = SQL_C_CHAR;  
      catalogResult[i].BufferLength = (bufferSize + 1);  
      catalogResult[i].TargetValuePtr = malloc( sizeof(unsigned char)*catalogResult[i].BufferLength );  
   }  
  
   // Set up the binding. This can be used even if the statement is closed by closeStatementHandle  
   for ( i = 0 ; i < numCols ; i++ )  
      retCode = SQLBindCol(hstmt, (SQLUSMALLINT)i + 1, catalogResult[i].TargetType, catalogResult[i].TargetValuePtr, catalogResult[i].BufferLength, &(catalogResult[i].StrLen_or_Ind));  
  
   retCode = SQLTables( hstmt, (SQLWCHAR*)SQL_ALL_CATALOGS, SQL_NTS, L"", SQL_NTS, L"", SQL_NTS, L"", SQL_NTS );  
   retCode = SQLFreeStmt(hstmt, SQL_CLOSE);  
  
   retCode = SQLTables( hstmt, dbName, SQL_NTS, userName, SQL_NTS, L"%", SQL_NTS, L"TABLE", SQL_NTS );  
  
   for ( retCode = SQLFetch(hstmt) ; retCode == SQL_SUCCESS || retCode == SQL_SUCCESS_WITH_INFO ; retCode = SQLFetch(hstmt), ++count )  
      if ( count == 1 )  
         StringCchPrintfW( firstTableName, 1024, L"%hs", catalogResult[2].TargetValuePtr );  
   retCode = SQLFreeStmt(hstmt, SQL_CLOSE);  
  
   wprintf( L"Select all data from the first table (%s)\n", firstTableName );  
   StringCchPrintfW( selectAllQuery, bufferSize, L"SELECT * FROM %s", firstTableName );  
  
   retCode = SQLExecDirect(hstmt, selectAllQuery, SQL_NTS);  
   printStatementResult(hstmt);  
}  

参照

ODBC API リファレンス
ODBC ヘッダー ファイル
ODBC のサンプル プログラム