MySQL :: MySQL 8.4 C API Developer Guide :: 5.4.74 mysql_session_track_get_first() (original) (raw)

5.4.74 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)

Description

MySQL implements a session tracker mechanism whereby the server returns information about session state changes to clients. To control which notifications the server provides about state changes, client applications set system variables having names of the formsession_track_ _`xxx`_, such assession_track_state_change,session_track_schema, andsession_track_system_variables. See Server Tracking of Client Session State.

Change notification occurs in the MySQL client/server protocol, which includes tracker information in OK packets so that session state changes can be detected. To enable client applications to extract state-change information from OK packets, the MySQL C API provides a pair of functions:

Themysql_session_track_get_first() parameters are used as follows. These descriptions also apply tomysql_session_track_get_next(), which takes the same parameters.

enum enum_session_state_type  
{  
  SESSION_TRACK_SYSTEM_VARIABLES,            /* Session system variables */  
  SESSION_TRACK_SCHEMA,                      /* Current schema */  
  SESSION_TRACK_STATE_CHANGE,                /* Session state changes */  
  SESSION_TRACK_GTIDS,                       /* GTIDs */  
  SESSION_TRACK_TRANSACTION_CHARACTERISTICS, /* Transaction characteristics */  
  SESSION_TRACK_TRANSACTION_STATE            /* Transaction state */  
};

The members of that enumeration may change over time as MySQL implements additional session-information trackers. To make it easy for applications to loop over all possible tracker types regardless of the number of members, theSESSION_TRACK_BEGIN andSESSION_TRACK_END symbols are defined to be equal to the first and last members of theenum_session_state_type enumeration. The example code shown later in this section demonstrates this technique. (Of course, if the enumeration members change, you must recompile your application to enable it to take account of new trackers.)

The following discussion describes how to interpret thedata and length values according to the type value. It also indicates which system variable enables notifications for each tracker type.

Consider a session consisting of the following statements, including one to enable the transaction state tracker: 

1. SET @@SESSION.session_track_transaction_info='STATE';  
2. START TRANSACTION;  
3. SELECT 1;  
4. INSERT INTO t1 () VALUES();  
5. INSERT INTO t1 () VALUES(1, RAND());  
6. COMMIT;

With transaction state tracking enabled, the followingdata values result from those statements: 

1. ________  
2. T_______  
3. T_____S_  
4. T___W_S_  
5. T___WsS_  
6. ________

Return Values

Zero for success. Nonzero if an error occurred.

Example

The following example shows how to callmysql_session_track_get_first() andmysql_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). It is assumed that the application has set thesession_track_ _`xxx`_ system variables that enable the notifications it wishes to receive.

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));
  return;
}

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));
  mysql_free_result(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)
  {
    /* print info type and initial data */
    printf("Type=%d:\n", type);
    printf("mysql_session_track_get_first(): length=%d; data=%*.*s\n",
           (int) length, (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(): length=%d; data=%*.*s\n",
             (int) length, (int) length, (int) length, data);
    }
  }
}