search

microsoft / ODBC-Specification

Microsoft ODBC Specification
Other
121 stars 40 forks source link

SQLGetNestedHandle - wording #81

Closed matthew-wozniczka closed 7 years ago

matthew-wozniczka commented 7 years ago

Section 6.2.1 (Usage) says:

Nested statement handles are in the prepared state and can be used to describe results once the parent statement handle is in the prepared or executed state.

I don't think this is true (always), should be reworded.

matthew-wozniczka commented 7 years ago

It also states:

Applications can fetch data from the nested statement handle once SQLNextColumn returns the ordinal associated with the nested statement.

But can't SQLGetNestedColumn be used for any column after a successful SQLFetch/SQLFetchScroll (subject to SQL_GETDATA_EXTENSIONS)?

matthew-wozniczka commented 7 years ago

Here's another one:

Applications SHOULD call SQLCloseCursor on the nested handle when finished reading results.

What is meant exactly by 'SHOULD'? What are the implications of doing so (or not)?

mikepizzo commented 7 years ago

Updated paragraph to read:

"Nested statement handles can be used to describe results once the parent statement handle is in the prepared or executed state. Applications can fetch data from the nested statement handle once the driver returns SQL_DATA_AVAILABLE for the particular column, and may allow fetching data at other times depending upon SQL_GETDATA_EXTENSIONS."

The implications of not calling SQLCloseCursor are spelled out in a subsequent paragraph:

"Unless the SQL_GD_CONCURRENT bit within SQL_GETDATA_EXTENSIONS is specified, a subsequent call to retrieve data using SQLGetData, SQLFetch, SQLFetchScroll, or SQLNextColumn on the parent handle or a different nested statement handle implicitly closes the statement handle. If SQL_GD_CONCURRENT is specified, a subsequent call to retrieve data on the child statement handle does not affect any other statement handle.

Closing a statement handle implicitly closes and frees all child statement handles."

So, I think your point is, why do we say the client should call SQLCloseCursor, and not just let the default behavior happen. I prefer that the client call SQLCloseCursor because: 1) It's more explicit statement of intent 2) It may allow the driver to clean up resources sooner, even in the case where it would support GD_EXTENSIONS 3) It's good general practice

All that said, SHOULD (in all caps, as a conformance statement) might be a bit strong.

Changed to "Calling SQLCloseCursor on the nested handle closes the child cursor for the current parent row."