Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual 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. It was added in MySQL 5.7.4.

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

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

  • mysql: The connection handle.

  • 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 */

    To make it easy to loop over all possible types of session information, the SESSION_TRACK_BEGIN and SESSION_TRACK_END macros are defined as 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: The length is the length of the new default schema name and the data is the name.

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

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

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 a 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);

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