Rambler's Top100

(c)2009-2017 openinfotech.ru

СУБД HyTech

Документация
Функция htAddRecords

htAddRecords - Добавление пачки записей

Назначение

Функция позволяет добавить группу записей в таблицу. Добавление невозможно, если таблица открыта в режиме "только на чтение" или захвачена другими пользователями сети в монопольном режиме. Функция будет выполнять добавление не больше заданного количества записей в указанную (по обработчику) таблицу. Число добавляемых записей может быть меньше, чем указано во втором параметре функции. Если записей окажется больше, они добавлены не будут. Следует избегать задания числа добавляемых записей с очень большим запасом. Это приведет к неоправданным затратам ресурсов и возможному снижению производительности.

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

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

После завершения операции добавления все отвергнутые записи будут удалены (и могут быть выведены в таблицу PROBLEM ).

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

Источник получения добавляемых записей в функции не задан. Вместо этого пользователь должен указать адрес функции, которая будет вызываться при выполнении функции htAddRecords для формирования очередной пачки записей в буфере. Такой подход позволяет пользователю использовать любые источники (буфера памяти, файлы, результаты поисков и т.п.) по своему усмотрению.

Механизм взаимодействия функций можно описать следующим образом:

  • каждый вызов пользовательской функции fpfAddProc нумеруется (первый, очередной или последний); порядок вызова передается в качестве первого параметра;
  • переданный пользовательской функции fpfAddProc в качестве параметра флаг очередности вызова позволяет выполнить любые начальные и завершающие действия (например, открыть и закрыть файл и т.п.); вызов пользовательской функции с флагом "последний" не предполагает подготовки данных (значения других параметров нулевые) и предназначен для организации завершающих операций в пользовательской программе;
  • функция htAddRecords выделяет максимально возможный буфер для приема добавляемых записей и вызывает пользовательскую функцию fpfAddProc, сообщая ей адрес буфера, его длину, длину записи и номер, который получит первая запись пачки (остальные получат номера по порядку);
  • пользовательская функция fpfAddProc заполняет выделенный буфер телами добавляемых записей и возвращает размер заполненного участка буфера;
  • длина буфера должна быть кратна длине записи (что очевидно);
  • буфер может быть заполнен частично (правда, это снижает эффективность работы, так как увеличивается общее число вызовов);
  • если функция fpfAddProc вернет 0, это трактуется как необходимость завершения операции добавления.

Пользовательская функции fpfAddProc получает в качестве третьего параметра указатель, заданный пользователем при вызове htAddRecords. Этот указатель служит для связи call-back функции с пользовательской программой, позволяя избежать необходимости использования глобальных переменных.

Прототип:

long HTAPI htAddRecords(
  THANDLE 	hTable,		/* Обработчик для таблицы */
  long 		gAppendLim, 	/* Число записей для добавления (максимум) */
  LPAFUNC 	fpfAddProc, 	/* Пользовательская функция подготовки данных */
  LPEFUNC 	fpfErrProc, 	/* Пользовательская функция обработки ошибок */
  void far 	*fpUser, 	/* Пользовательский параметр для call-back */
  int 		nDenyOut	/* != 0 вывод отвергнутых записей в таблицу */
);

Параметры:

 hTable
 Обработчик для таблицы
 gAppendLim
 Число записей для добавления (максимум)
 fpfAddProc
Пользовательская функция подготовки данных. Имеет тип AFUNC
 fpfErrProc
Пользовательская функция обработки ошибок. Имеет тип EFUNC . Если функция обработки ошибок не задана (ее адрес NULL), используется "внутренняя" функция, прекращающая операцию при первой же ошибке (возвращает ERROR_ABORT).
 fpUser
 Пользовательский параметр для call-back
 nDenyOut
 != 0 вывод отвергнутых записей в таблицу

Результат

В качестве кода завершения функция htAddRecords возвращает длинное целое со знаком.

меньше 0 его следует интерпретировать как код ошибки
> 0 содержит счетчик отвергнутых записей
= 0 отвергнутых записей не найдено

Пример.

Добавление пачки из 1000 записей из файла SOURCE. Отвергнутые записи просто удаляются.

 #define TRUE 1
 #define FALSE 0
 long rc;
 THANDLE hTable;
 . . .
 /* Функция подготовки записей */
 static AFUNC Prepare
 {
	HFILE file;
	UINT wRead;
	switch( nOrder )
	{
	 case ADD_FIRST: /* Первый вызов - откроем файл */
		if( !(file = _lopen( (LPSTR)fpUser, READ )) )
		 return 0;
	 case ADD_NEXT: /* Читаем очередную порцию данных */
		wRead = _lread( file, fpParm->fpBuf, fpParm->wBufLen );
		break;
	 case ADD_LAST: /* Последний вызов - закрытие файла */
		_lclose( file );
		wRead = 0; /* Код возврата здесь не имеет значения */
	}
	return wRead;
 }
 . . .
 rc = htAddRecords( hTable, 1000L, Prepare, (LPEFUNC)NULL, "SOURCE", FALSE );
 if( rc < 0L )
	/* Обработка ошибок */
 else if( rc == 0L )
	/* Успешное завершение */
 else
	/* Отвергнуто rc записи(ей) */