Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 38.0Mb
PDF (A4) - 38.1Mb
PDF (RPM) - 36.7Mb
HTML Download (TGZ) - 9.9Mb
HTML Download (Zip) - 9.9Mb
HTML Download (RPM) - 8.7Mb
Man Pages (TGZ) - 209.7Kb
Man Pages (Zip) - 318.9Kb
Info (Gzip) - 3.5Mb
Info (Zip) - 3.5Mb
Excerpts from this Manual

MySQL 5.7 Reference Manual  /  ...  /  mysql_session_track_get_first() mysql_session_track_get_first()

int mysql_session_track_get_first(MYSQL *mysql, enum enum_session_state_type type, const char **data, size_t *length)


This function fetches the first session state-change information received from the server.

To control notification for changes to session state, use the session_track_state_change, session_track_schema, session_track_system_variables, and session_track_gtids system variables (see Section 5.1.7, “Server System Variables”).

The function parameters are used as follows. These descriptions also apply to mysql_session_track_get_next(), which takes the same parameters.

  • mysql: The connection handler.

  • type: The type of information to retrieve. Permitted values for this parameter are the members of the enum_session_state_type enumeration defined in mysql_com.h:

    enum enum_session_state_type
      SESSION_TRACK_SYSTEM_VARIABLES, /* Session system variables */
      SESSION_TRACK_SCHEMA,           /* Current schema */
      SESSION_TRACK_STATE_CHANGE      /* track session state changes */
      SESSION_TRACK_GTIDS,            /* track GTIDs/*

    To make it easy to loop over all possible types of session information, the SESSION_TRACK_BEGIN and SESSION_TRACK_END macros are defined to be equal to the first and last members of the enum_session_state_type enumeration. The example code shown later in this section demonstrates this technique.

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

  • length: The address of a size_t variable. Following a successful call, this variable contains the length of the data pointed to by the data parameter.

Following a successful call, interpret the data and length values according to the type value, as follows:

  • SESSION_TRACK_SCHEMA: data is the new default schema name and length is the name length.

  • SESSION_TRACK_SYSTEM_VARIABLES: When a session system variable changes, two values per variable are returned (in separate calls). For the first call, data is the variable name and length is the name length. For the second call, data is the variable value and length is the value length. value Both data values are represented as strings.

  • SESSION_TRACK_STATE_CHANGE: data is a byte containing a boolean flag that indicates whether session state changes occurred and length should be 1. The flag is represented as an ASCII value, not a binary (for example, '1', not 0x01).

  • SESSION_TRACK_GTIDS: data contains the GTID set information and length is its length.

Return Values

Zero for success. Nonzero if an error occurred.




The following example shows how to call mysql_session_track_get_first() and mysql_session_track_get_next() to retrieve and display all available session state-change information following successful execution of an SQL statement string (represented by stmt_str).

printf("Execute: %s\n", stmt_str);

if (mysql_query(mysql, stmt_str) != 0)
  fprintf(stderr, "Error %u: %s\n",
           mysql_errno(mysql), mysql_error(mysql));

MYSQL_RES *result = mysql_store_result(mysql);
if (result) /* there is a result set to fetch */
  /* ... process rows here ... */
  printf("Number of rows returned: %lu\n",
          (unsigned long) mysql_num_rows(result));
else        /* there is no result set */
  if (mysql_field_count(mysql) == 0)
    printf("Number of rows affected: %lu\n",
            (unsigned long) mysql_affected_rows(mysql));
  else      /* an error occurred */
    fprintf(stderr, "Error %u: %s\n",
             mysql_errno(mysql), mysql_error(mysql));

/* extract any available session state-change information */
enum enum_session_state_type type;
for (type = SESSION_TRACK_BEGIN; type <= SESSION_TRACK_END; type++)
  const char *data;
  size_t length;

  if (mysql_session_track_get_first(mysql, type, &data, &length) == 0)
    printf("Type=%d:\n", type);
    printf("mysql_session_track_get_first() returns: %*.*s\n",
            (int) length, (int) length, data);

    /* check for more data */
    while (mysql_session_track_get_next(mysql, type, &data, &length) == 0)
      printf("mysql_session_track_get_next() returns: %*.*s\n",
              (int) length, (int) length, data);

User Comments
Sign Up Login You must be logged in to post a comment.