Rambler's Top100

(c)2009-2017 openinfotech.ru

СУБД HyTech

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

htModifyRecords - Модификация подмножества записей таблицы

Назначение:

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

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

После обработки пользователем запись проверяется на допустимость значений. В случае удачного прохождения проверки запись добавляется в журнал изменений.

Функция htModifyRecords обеспечивает сохранность значений суррогатного ключа (при наличии такового), поэтому пользовательская функция вольна поступать с этим ключом как ей вздумается.

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

- ERROR_ABORT - прекратить операцию; в этом случае журнал изменений "откатывается" в первоначальное состояние;

- ERROR_DELETE - пометить "плохую" запись как удаленную; после завершения операции модификации все отвергнутые записи будут удалены (и могут быть выведены в таблицу PROBLEM).

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

Если функция обработки ошибок не задана (ее адрес NULL), используется "внутренняя" функция, прекращающая операцию при первой же ошибке (возвращает ERROR_ABORT).

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

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

Прототип:

 long HTAPI htModifyRecords(
	LPSAB fpSrc, /* Адрес БДС, содержащего подмножество записей */
	LPMFUNC fpfMdfProc, /* Функция модификации записей */
	LPEFUNC fpfErrProc, /* Пользовательская функция обработки ошибок */
			 /* NULL - ошибки отменяют операцию */
	void far *fpUser, /* Пользовательский параметр для call-back */
	int nDenyOut /* != 0 вывод отвергнутых записей в таблицу */
 );

Параметры

fpSrc
Адрес БДС, содержащего подмножество записей
fpfMdfProc
Функция модификации записей. Функция имеет тип MFUNC
fpfErrProc
Пользовательская функция обработки ошибок Функция имеет тип EFUNC
fpUser
Пользовательский параметр для call-back
nDenyOut
!= 0 вывод отвергнутых записей в таблицу

Результат:

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

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

Пример.

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

 #define TRUE 1
 #define FALSE 0
 typedef struct tagREC { /* Структура записи таблицы */
 char name[10];
 char sex;
 int depart;
 } REC;
 . . .
 /* Функция модификации записей */
 static MFUNC Edit
 {
	((REC far*)fpRecord)->depart = 11;
	return TRUE;
 }
 . . .
 {
 long rc;
 int depart = 10;
 SAB sab;
 THANDLE hTable;
 . . .
 /* Ищем записи с "номером_отдела" равным 10 */
 if( !htSearch( NULL, &sab, hTable, 3, EQUAL, &depart, NULL ) )
	/* Обработка ошибок */
 . . .
 /* Заменить номер отдела */
 rc = htModifyRecords( sab, Edit, (LPEFUNC)NULL, NULL, FALSE );
 if( rc < 0L )
	 /* Ошибка модификации */
 else if( rc == 0L )
	 /* Успешное завершение */
 else
	 /* Отвергнуто rc записи(ей) */
 }