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)

Описание

MySQL реализует механизм отслеживания сеансов, посредством которого сервер возвращает клиентам информацию об изменениях состояния сеанса. Для управления уведомлениями сервера об изменениях состояния, клиентские приложения устанавливают переменные системы, имеющие имена вида session_track_xxx, такие как , , и . См. .

Уведомление об изменениях происходит в протоколе MySQL клиент/сервер, который включает информацию о трекере в пакетах OK, чтобы можно было обнаружить изменения состояния сеанса. Для того, чтобы клиентские приложения могли извлечь информацию об изменениях состояния из пакетов OK, API MySQL C предоставляет пару функций:

mysql_session_track_get_first() извлекает первую часть информации об изменениях состояния, полученной от сервера.
mysql_session_track_get_next() извлекает оставшуюся информацию об изменениях состояния, полученную от сервера. После успешного вызова mysql_session_track_get_first(), эту функцию следует вызывать повторно, пока она возвращает успех.

Параметры mysql_session_track_get_first() используются следующим образом. Эти описания также относятся к mysql_session_track_get_next(), которая принимает те же параметры.

mysql: обработчик соединения.
type: тип трекера, указывающий какой тип информации извлечь. Разрешённые значения трекеров являются членами перечисления enum_session_state_type, определённого в mysql_com.h:
```
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 */
};
```
Члены этого перечисления могут меняться со временем по мере реализации MySQL дополнительных трекеров информации о сеансах. Для облегчения прохода приложениями по всем возможным типам трекеров независимо от количества членов, определены символы SESSION_TRACK_BEGIN и SESSION_TRACK_END, которые равны первому и последнему членам перечисления enum_session_state_type. Приведённый далее в этом разделе пример кода демонстрирует эту технику. (Конечно, если члены перечисления изменятся, необходимо перекомпилировать ваше приложение, чтобы оно учитывало новые трекеры.)
data: адрес переменной типа const char *. После успешного вызова эта переменная указывает на возвращённые данные, которые следует рассматривать как только для чтения.
length: адрес переменной типа size_t. После успешного вызова эта переменная содержит длину данных, на которые указывает параметр data.

Ниже приведено описание того, как интерпретировать значения data и length в зависимости от значения type. Также указана, какая системная переменная разрешает уведомления для каждого типа трекера.

SESSION_TRACK_SCHEMA: Этот тип трекера указывает, что установлена схема по умолчанию. data — строка с новым именем схемы по умолчанию. length — длина строки.

Для включения уведомлений для этого типа трекера, включите системную переменную.
SESSION_TRACK_SYSTEM_VARIABLES: Этот тип трекера указывает, что одной или нескольким системным переменным сессии присвоено значение. При присвоении значения сессионной системной переменной возвращаются два значения на переменную (в отдельных вызовах). В первом вызове data — строка, содержащая имя переменной, а length — длина строки. Во втором вызове data — строка, содержащая значение переменной, а length — длина строки.

По умолчанию уведомления включены для этих системных переменных сессии:

Чтобы изменить уведомления по умолчанию для этого типа трекера, задайте системную переменную в виде списка переменных через запятую, изменения которых необходимо отслеживать, или * для отслеживания изменений всех переменных. Для отключения уведомлений об изменениях значений сессионных переменных установите в пустую строку.
SESSION_TRACK_STATE_CHANGE: Этот тип трекера указывает изменение некоторых отслеживаемых атрибутов состояния сессии. data — байт, содержащий логический флаг, указывающий, произошли ли изменения состояния сессии. length должно быть равно 1. Флаг представлен как значение ASCII, а не двоичное (например, '1', а не 0x01).

Для включения уведомлений для этого типа трекера включите системную переменную.

Этот трекер сообщает об изменениях этих атрибутов состояния сессии:
- Схема по умолчанию (база данных).
- Значения системных переменных, специфичные для сессии.
- Переменные, определенные пользователем.
- Временные таблицы.
- Подготовленные запросы.
SESSION_TRACK_GTIDS: Этот тип трекера указывает, что доступны GTID. data содержит строку GTID. length — длина строки. Строка GTID имеет стандартный формат для задания набора значений GTID; см. .

Для включения уведомлений для этого типа трекера установите системную переменную.
SESSION_TRACK_TRANSACTION_CHARACTERISTICS: Этот тип трекера указывает, что доступны характеристики транзакции. data — строка, содержащая данные характеристик. length — длина строки. Строка данных трекера характеристик может быть пустой или содержать одну или несколько SQL-команд, каждая из которых завершается точкой с запятой:
- Если нет применимых характеристик, строка пустая. Применяются значения по умолчанию для сессии. (Для уровня изоляции и режима доступа значениями по умолчанию являются значения сессии системных переменных и ).
- Если транзакция была явно начата, строка содержит команду или команды, необходимые для перезапуска транзакции с теми же характеристиками. Как правило, это команда (возможно, с одной или несколькими из READ ONLY, READ WRITE и WITH CONSISTENT SNAPSHOT). Если есть какие-либо характеристики, которые нельзя передать с помощью , такие как ISOLATION LEVEL, добавляется соответствующая команда (например, SET TRANSACTION ISOLATION LEVEL SERIALIZABLE; START TRANSACTION READ WRITE;).
- Если транзакция не была явно начата, но были настроены одноразовые характеристики, которые применяются только к следующей транзакции, генерируется команда для дублирования этой настройки (например, SET TRANSACTION READ ONLY;).
  
  Характеристики следующей транзакции могут быть установлены с помощью без ключевых слов GLOBAL или SESSION, или путем установки системных переменных и с использованием синтаксиса, который применяется только к следующей транзакции:
```
SET @@transaction_isolation = value;
SET @@transaction_read_only = value;
```
  Дополнительную информацию о уровнях охвата характеристик транзакций и способах их установки см. в .
Для включения уведомлений для этого типа трекера установите системную переменную в CHARACTERISTICS (что также включает тип трекера SESSION_TRACK_TRANSACTION_STATE).

Отслеживание характеристик транзакций позволяет клиенту определить, как перезапустить транзакцию в другой сессии, чтобы она имела те же характеристики, что и в исходной сессии.

Поскольку характеристики могут быть установлены с помощью до начала транзакции, клиенту не безопасно полагать, что характеристик транзакции нет, если нет активной транзакции. Поэтому небезопасно не отслеживать характеристики транзакции и просто переключать соединение, когда транзакция не активна (независимо от того, обнаружено ли это с помощью трекера состояния транзакции или традиционного флага SERVER_STATUS_IN_TRANS). Клиент должен подписаться на трекер характеристик транзакции, если он может захотеть переключить свою сессию на другое соединение в какой-то момент, и транзакции могут использоваться.

Трекер характеристик отслеживает изменения в одноразовых характеристиках, которые применяются только к следующей транзакции. Он не отслеживает изменения системных переменных. Поэтому клиент дополнительно должен отслеживать системные переменные и для правильного определения значений параметров по умолчанию сессии, которые применяются, когда значения характеристик следующей транзакции пусты. (Для отслеживания этих переменных укажите их в значении системной переменной ).
SESSION_TRACK_TRANSACTION_STATE: Этот тип трекера указывает, что доступна информация о состоянии транзакции. data — строка, содержащая символы ASCII, каждый из которых указывает какой-либо аспект состояния транзакции. length — длина строки (всегда 8).

Для включения уведомлений для этого типа трекера установите системную переменную в STATE.

Отслеживание состояния транзакции позволяет клиенту определить, активна ли транзакция и можно ли перенести ее в другую сессию без отката.

Область действия элемента трекера — транзакция. Все флаги, указывающие состояние, сохраняются до завершения транзакции (фиксации или отката). По мере добавления заявок в транзакцию в последующих значениях данных трекера могут быть установлены дополнительные флаги. Однако ни один флаг не сбрасывается до завершения транзакции.

Состояние транзакции сообщается как строка, содержащая последовательность символов ASCII. Каждый активный статус имеет уникальный символ, назначенный ему, а также фиксированное положение в последовательности. В следующей таблице описаны разрешенные значения для позиций с 1 по 8 в последовательности:
- Позиция 1: Активна ли активная транзакция.
  - T: Активна явно начатая транзакция.
  - I: Активна неявно начатая транзакция (implicit).
  - _: Нет активной транзакции.
- Позиция 2: Считывались ли нетранзакционные таблицы в контексте текущей транзакции.
  - r: Были прочитаны одна или несколько нетранзакционных таблиц.
  - _: Пока не были прочитаны нетранзакционные таблицы.

Возвращаемые значения

Ноль при успехе. ненулевое значение, если произошла ошибка.

Ошибки

Нет.

Пример

Следующий пример демонстрирует, как вызвать mysql_session_track_get_first() и mysql_session_track_get_next() для получения и отображения всей доступной информации о состоянии изменений сеанса после успешного выполнения строки SQL-запроса (представленной stmt_str). Предполагается, что приложение установило системные переменные session_track_xxx, которые позволяют получать желаемые уведомления.

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