Skip to content

Commit 414d704

Browse files
rwestMSFTrwestMSFT
authored
Refresh Data type article and add back image (UUF 454025) (#34729)
1 parent eb1bb3b commit 414d704

File tree

1 file changed

+42
-48
lines changed

1 file changed

+42
-48
lines changed

‎docs/odbc/reference/appendixes/converting-data-from-sql-to-c-data-types.md

Lines changed: 42 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
---
22
title: "Converting Data from SQL to C Data Types"
3-
description: "Converting Data from SQL to C Data Types"
3+
description: Learn about converting data from SQL to C data types.
44
author: David-Engel
55
ms.author: davidengel
6-
ms.date: "01/19/2017"
6+
ms.reviewer: randolphwest
7+
ms.date: 07/17/2025
78
ms.service: sql
89
ms.subservice: connectivity
910
ms.topic: reference
@@ -18,49 +19,42 @@ helpviewer_keywords:
1819
- "converting data from SQL to c types [ODBC], about converting"
1920
- "C data types [ODBC], converting from SQL types"
2021
---
21-
# Converting Data from SQL to C Data Types
22-
When an application calls **SQLFetch**, **SQLFetchScroll**, or **SQLGetData**, the driver retrieves the data from the data source. If necessary, it converts the data from the data type in which the driver retrieved it to the data type specified by the *TargetType* argument in **SQLBindCol** or **SQLGetData.** Finally, it stores the data in the location pointed to by the *TargetValuePtr* argument in **SQLBindCol** or **SQLGetData** (and the SQL_DESC_DATA_PTR field of the ARD).
23-
24-
The following table shows the supported conversions from ODBC SQL data types to ODBC C data types. A filled circle indicates the default conversion for a SQL data type (the C data type to which the data will be converted when the value of *TargetType* is SQL_C_DEFAULT). A hollow circle indicates a supported conversion.
25-
26-
For an ODBC *3.x* application working with an ODBC *2.x* driver, conversion from driver-specific data types might not be supported.
27-
28-
The format of the converted data is not affected by the Windows country/region setting.
29-
30-
The tables in the following sections describe how the driver or data source converts data retrieved from the data source; drivers are required to support conversions to all ODBC C data types from the ODBC SQL data types that they support. For a given ODBC SQL data type, the first column of the table lists the legal input values of the *TargetType* argument in **SQLBindCol** and **SQLGetData**. The second column lists the outcomes of a test, often using the *BufferLength* argument specified in **SQLBindCol** or **SQLGetData**, which the driver performs to determine whether it can convert the data. For each outcome, the third and fourth columns list the values placed in the buffers specified by the *TargetValuePtr* and *StrLen_or_IndPtr* arguments specified in **SQLBindCol** or **SQLGetData** after the driver has attempted to convert the data. (The *StrLen_or_IndPtr* argument corresponds to the SQL_DESC_OCTET_LENGTH_PTR field of the ARD.) The last column lists the SQLSTATE returned for each outcome by **SQLFetch**, **SQLFetchScroll**, or **SQLGetData**.
31-
32-
If the *TargetType* argument in **SQLBindCol** or **SQLGetData** contains an identifier for an ODBC C data type not shown in the table for a given ODBC SQL data type, **SQLFetch**, **SQLFetchScroll**, or **SQLGetData** returns SQLSTATE 07006 (Restricted data type attribute violation). If the *TargetType* argument contains an identifier that specifies a conversion from a driver-specific SQL data type to an ODBC C data type and this conversion is not supported by the driver, **SQLFetch**, **SQLFetchScroll**, or **SQLGetData** returns SQLSTATE HYC00 (Optional feature not implemented).
33-
34-
Although it is not shown in the tables, the driver returns SQL_NULL_DATA in the buffer specified by the *StrLen_or_IndPtr* argument when the SQL data value is NULL. For an explanation of the use of *StrLen_or_IndPtr* when multiple calls are made to retrieve data, see the [SQLGetData](../../../odbc/reference/syntax/sqlgetdata-function.md) function description. When SQL data is converted to character C data, the character count returned in \**StrLen_or_IndPtr* does not include the null-termination byte. If *TargetValuePtr* is a null pointer, **SQLGetData** returns SQLSTATE HY009 (Invalid use of null pointer); in **SQLBindCol**, this unbinds the column.
35-
36-
The following terms and conventions are used in the tables:
37-
38-
- **Byte length of data** is the number of bytes of C data available to return in **TargetValuePtr*, whether or not the data will be truncated before it is returned to the application. For string data, this does not include the space for the null-termination character.
39-
40-
- **Character byte length** is the total number of bytes needed to display the data in character format. This is as defined for each C data type in the section [Display Size](../../../odbc/reference/appendixes/display-size.md), except that character byte length is in bytes while the display size is in characters.
41-
42-
- Words in *italics* represent function arguments or elements of the SQL grammar. For the syntax of grammar elements, see [Appendix C: SQL Grammar](../../../odbc/reference/appendixes/appendix-c-sql-grammar.md).
43-
44-
This section contains the following topics.
45-
46-
- [SQL to C: Character](../../../odbc/reference/appendixes/sql-to-c-character.md)
47-
48-
- [SQL to C: Numeric](../../../odbc/reference/appendixes/sql-to-c-numeric.md)
49-
50-
- [SQL to C: Bit](../../../odbc/reference/appendixes/sql-to-c-bit.md)
51-
52-
- [SQL to C: Binary](../../../odbc/reference/appendixes/sql-to-c-binary.md)
53-
54-
- [SQL to C: Date](../../../odbc/reference/appendixes/sql-to-c-date.md)
55-
56-
- [SQL to C: GUID](../../../odbc/reference/appendixes/sql-to-c-guid.md)
57-
58-
- [SQL to C: Time](../../../odbc/reference/appendixes/sql-to-c-time.md)
59-
60-
- [SQL to C: Timestamp](../../../odbc/reference/appendixes/sql-to-c-timestamp.md)
61-
62-
- [SQL to C: Year-Month Intervals](../../../odbc/reference/appendixes/sql-to-c-year-month-intervals.md)
63-
64-
- [SQL to C: Day-Time Intervals](../../../odbc/reference/appendixes/sql-to-c-day-time-intervals.md)
65-
66-
- [SQL to C Data Conversion Examples](../../../odbc/reference/appendixes/sql-to-c-data-conversion-examples.md)
22+
# Convert data from SQL to C data types
23+
24+
When an application calls `SQLFetch`, `SQLFetchScroll`, or `SQLGetData`, the driver retrieves the data from the data source. If necessary, it converts the data from the data type in which the driver retrieved it to the data type specified by the *TargetType* argument in `SQLBindCol` or `SQLGetData`. Finally, it stores the data in the location pointed to by the *TargetValuePtr* argument in `SQLBindCol` or `SQLGetData` (and the `SQL_DESC_DATA_PTR` field of the ARD).
25+
26+
The following table shows the supported conversions from ODBC SQL data types to ODBC C data types. A filled circle indicates the default conversion for a SQL data type (the C data type to which the data will be converted when the value of *TargetType* is `SQL_C_DEFAULT`). A hollow circle indicates a supported conversion.
27+
28+
For an ODBC *3.x* application working with an ODBC *2.x* driver, conversion from driver-specific data types might not be supported.
29+
30+
The format of the converted data isn't affected by the Windows country/region setting.
31+
32+
:::image type="content" source="media/apd1b.gif" alt-text="Diagram of supported conversions: ODBC C to SQL data types.":::
33+
34+
The tables in the following sections describe how the driver or data source converts data retrieved from the data source; drivers are required to support conversions to all ODBC C data types from the ODBC SQL data types that they support. For a given ODBC SQL data type, the first column of the table lists the legal input values of the *TargetType* argument in `SQLBindCol` and `SQLGetData`. The second column lists the outcomes of a test, often using the *BufferLength* argument specified in `SQLBindCol` or `SQLGetData`, which the driver performs to determine whether it can convert the data. For each outcome, the third and fourth columns list the values placed in the buffers specified by the *TargetValuePtr* and *StrLen_or_IndPtr* arguments specified in `SQLBindCol` or `SQLGetData` after the driver has attempted to convert the data. (The *StrLen_or_IndPtr* argument corresponds to the `SQL_DESC_OCTET_LENGTH_PTR` field of the ARD.) The last column lists the SQLSTATE returned for each outcome by `SQLFetch`, `SQLFetchScroll`, or `SQLGetData`.
35+
36+
If the *TargetType* argument in `SQLBindCol` or `SQLGetData` contains an identifier for an ODBC C data type not shown in the table for a given ODBC SQL data type, `SQLFetch`, `SQLFetchScroll`, or `SQLGetData` returns SQLSTATE 07006 (Restricted data type attribute violation). If the *TargetType* argument contains an identifier that specifies a conversion from a driver-specific SQL data type to an ODBC C data type and this conversion isn't supported by the driver, `SQLFetch`, `SQLFetchScroll`, or `SQLGetData` returns SQLSTATE HYC00 (Optional feature not implemented).
37+
38+
Although it's not shown in the tables, the driver returns `SQL_NULL_DATA` in the buffer specified by the *StrLen_or_IndPtr* argument when the SQL data value is `NULL`. For an explanation of the use of *StrLen_or_IndPtr* when multiple calls are made to retrieve data, see the [SQLGetData Function](../syntax/sqlgetdata-function.md) function description. When SQL data is converted to character C data, the character count returned in *StrLen_or_IndPtr* doesn't include the null-termination byte. If *TargetValuePtr* is a null pointer, `SQLGetData` returns SQLSTATE HY009 (Invalid use of null pointer); in `SQLBindCol`, this unbinds the column.
39+
40+
The following terms and conventions are used in the tables:
41+
42+
- **Byte length of data** is the number of bytes of C data available to return in *TargetValuePtr*, whether or not the data is truncated before it's returned to the application. For string data, this doesn't include the space for the null-termination character.
43+
44+
- **Character byte length** is the total number of bytes needed to display the data in character format. This is as defined for each C data type in the section [Display Size](display-size.md), except that character byte length is in bytes while the display size is in characters.
45+
46+
- Words in *italics* represent function arguments or elements of the SQL grammar. For the syntax of grammar elements, see [Appendix C: SQL Grammar](appendix-c-sql-grammar.md).
47+
48+
This section contains the following articles.
49+
50+
- [SQL to C: Character](sql-to-c-character.md)
51+
- [SQL to C: Numeric](sql-to-c-numeric.md)
52+
- [SQL to C: Bit](sql-to-c-bit.md)
53+
- [SQL to C: Binary](sql-to-c-binary.md)
54+
- [SQL to C: Date](sql-to-c-date.md)
55+
- [SQL to C: GUID](sql-to-c-guid.md)
56+
- [SQL to C: Time](sql-to-c-time.md)
57+
- [SQL to C: Timestamp](sql-to-c-timestamp.md)
58+
- [SQL to C: Year-Month Intervals](sql-to-c-year-month-intervals.md)
59+
- [SQL to C: Day-Time Intervals](sql-to-c-day-time-intervals.md)
60+
- [SQL to C Data Conversion Examples](sql-to-c-data-conversion-examples.md)

0 commit comments

Comments
 (0)