MySQL Bugs: #96349: Documentation for mysql_session_track_get

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

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.

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.

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

>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.

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.
"

>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.

Hi,

I am afraid that you are correct.

That chapter on the page should probably be omitted altogether.

Verified as a documentation bug.

>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.

Your note has been forwarded to the correct department.

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.

Thank you, Paul .......