Bug #96349 Documentation for mysql_session_track_get_first is incorrect for GTIDs
Submitted: 27 Jul 2019 2:18 Modified: 3 Oct 2019 14:41
Reporter: Nicholas Williams Email Updates:
Status: Closed Impact on me:
None 
Category:Connector / C Documentation Severity:S3 (Non-critical)
Version:5.7.17-13 OS:Any
Assigned to: Paul DuBois CPU Architecture:Any

[27 Jul 2019 2:18] Nicholas Williams
Description:
The Connector/C documentation for mysql_session_track_get_first (https://dev.mysql.com/doc/refman/8.0/en/mysql-session-track-get-first.html) is incorrect for GTIDs in both 5.7 and 8.0. It says:

"`data` contains encoded GTID data, `length` indicates the data length. Once the `data` value has been extracted, it must be further interpreted into three parts: Encoding specification, length of GTIDs string, GTIDs string. Currently, there is only one encoding specification, so this should always be 0. The GTIDs string is in the standard format for specifying a set of GTID values; see GTID Sets."

Based on this documentation, when I made this call:

mysql_session_track_get_first(mysql, SESSION_TRACK_GTIDS, &data, &length)

I expected the first byte of `data` to be 0 ("this should always be 0"), the second byte of `data` to be the length of the GTID string, and the rest of `data` to be the GTID string. However, it's not. This is the full contents of `data`:

c2f6ac54-b00f-11e9-8429-0242ac120006:6

The `length` variable is 38, which matches the length of "c2f6ac54-b00f-11e9-8429-0242ac120006:6". 

If I manually retrieve `*data`, it is 99, which corresponds to "c" in ASCII. Likewise, `*(data + 1)` is 50, which corresponds to "2" in ASCII. (Per: http://www.asciitable.com/).

How to repeat:
const char *data;
size_t length;

mysql_session_track_get_first(mysql, type, &data, &length)
printf("mysql_session_track_get_first(): length=%d; data=%*.*s\n", (int) length, (int) length, (int) length, data);
printf("byte 1: %d\n", *data);
printf("byte 2: %d\n", *(data + 1));
printf("bytes 3-n: %s\n", data + 2);

Output:

mysql_session_track_get_**(): length=38; data=c2f6ac54-b00f-11e9-8429-0242ac120006:6
byte 1: 99
byte 2: 50
bytes 3-n: f6ac54-b00f-11e9-8429-0242ac120006:6

Suggested fix:
The documentation should be updated to get rid of all the incorrect information about the encoding specification 0 and the GTID length, and just say that `data` is the GTID string in the standard format for specifying a set of GTID values.
[27 Jul 2019 2:31] Nicholas Williams
Also, FWIW, no matter what I do, when using `SESSION_TRACK_GTIDS`, `mysql_session_track_get_next` seems to ALWAYS return non-zero. Only `mysql_session_track_get_first` ever returns zero. It seems like there's never more than one thing to return here when using `SESSION_TRACK_GTIDS`. Maybe that's as expected/by design, but if so, it seems prudent for the documentation to mention it.
[29 Jul 2019 13:41] MySQL Verification Team
Hi Mr. Williams,

Thank you for your bug report.

However, it seems that this issue has already been fixed in our documentation:

https://dev.mysql.com/doc/refman/5.7/en/mysql-session-track-get-first.html
[29 Jul 2019 13:52] Nicholas Williams
>Hi Mr. Williams,
>
>Thank you for your bug report.
>
>However, it seems that this issue has already been fixed in our documentation:
>
>https://dev.mysql.com/doc/refman/5.7/en/mysql-session-track-get-first.html

At that exact link you just sent me, there are no changes. It is still exactly like it was last week, incorrectly stating that the value has to be parsed into encoding specification, GTID length, and GTID. I even looked at the documentation on a completely different computer in case I had some weird caching going on, but still no difference. The documentation has not been fixed. Please re-open this.
[29 Jul 2019 14:00] MySQL Verification Team
Hi,

First of all, you should test your problem with latest API available, which is the one that comes with 5.7.27.

Second, if you are tracking SESSION_TRACK_GTIDS, you must do the following:

"
To enable notifications for this tracker type, set the session_track_gtids system variable.
"

Last, but not least, the same page states the following:

"
data: The address of a const char * variable. Following a successful call, this variable points to the returned data, which should be considered read only.
"
[29 Jul 2019 14:49] Nicholas Williams
>Hi,
>
>First of all, you should test your problem with latest API available, which is the one that comes with 5.7.27.

Yep, that's the version I'm using.

>Second, if you are tracking SESSION_TRACK_GTIDS, you must do the following:
>
>"To enable notifications for this tracker type, set the session_track_gtids system variable."

Yes, I'm setting that system variable.

>Last, but not least, the same page states the following:
>
>"data: The address of a const char * variable. Following a successful call, this variable points to the returned data, which should be considered read only."

Yes, and this is correct, but this is not the part to which I'm referring. I'm referring to this part of the documentation at the page you linked:

"SESSION_TRACK_GTIDS: This tracker type indicates that GTIDS are available. data contains encoded GTID data, length indicates the data length. Once the data value has been extracted, it must be further interpreted into three parts: Encoding specification, length of GTIDs string, GTIDs string. Currently, there is only one encoding specification, so this should always be 0. The GTIDs string is in the standard format for specifying a set of GTID values; see GTID Sets."

This part of the documentation is completely incorrect, as described IN DETAIL in my original bug report. Please read it and the documentation very carefully and you will see that I'm correct here.
[30 Jul 2019 11:57] MySQL Verification Team
Hi,

I am afraid that you are correct.

That chapter on the page should probably be omitted altogether.

Verified as a documentation bug.
[30 Jul 2019 20:56] Nicholas Williams
>That chapter on the page should probably be omitted altogether.

I don't think we want to omit it. It's vital information. Without it, we wouldn't know how to use SESSION_TRACK_GTIDS. It just needs to be fixed so that it gives the correct information.
[31 Jul 2019 12:10] MySQL Verification Team
Your note has been forwarded to the correct department.
[3 Oct 2019 14:41] Paul DuBois
Posted by developer:
 
Thanks for pointing out this problem.

It turns out that the encoding described in the manual is the encoding as performed on the server side and received on the client side internally. But after the client library receives the information, it performs the interpretation of that encoding itself, so that the C API function returns to its caller the simpler length + GTID string that you observed. I'll update the description:

SESSION_TRACK_GTIDS: This tracker type indicates that GTIDs are
available. data contains the GTID string. length is the string
length. The GTID string is in the standard format for specifying a
set of GTID values.
[4 Oct 2019 11:50] MySQL Verification Team
Thank you, Paul .......