Утилита REB

Утилита REB.

Выполняет перестройку структуры базы данных на основе текстового описания структуры в DBS-файлах или на основе получения готовой структуры из файла-шаблона. С помощью REB можно создавать новые файлы БД, удалять или менять структуру существующих файлов БД. В последнем случае содержимое этих файлов приводится к новой структуре.

Синтаксис вызова утилиты REB:

V32 -Reb[uild] <Имя_базы> {<Ключ>}

Допустимые ключи:

? - показать справку
P[attern] - в качестве новой структуры базы данных брать файл-шаблон.
Этот ключ регулирует способ получения программой REB новой структуры БД, к которой нужно приводить старую. Существует 2 способа:
1. Ключ Pattern не указан. Структура БД строится с помощью выполнения программ в DBS-файлах. Выполнение начинается с MAIN.DBS. DBS-программы разыскиваются по клиентскому RED-файлу.
  - до V14.57.1 если перед выполнением REB имелся доступный по серверному RED-файлу файл <Имя проекта>.DBP, то этот файл переименовывался в <Имя проекта>.DB$, но создавался новый DBP-файл - точная копия созданного DBD-файла.
2. В параметре ключа Pattern указан файл-шаблон. Готовая структура БД берется из указанного файла. В этом случае:
3. До V14.57.1. ключ Pattern можно было указать без параметра. В этом случае готовая структура БД бралась из файла <Имя проекта>.DBP, который разыскивался по серверному RED-файлу.
  - в HIS-файле 3-ей строкой сообщения о выполненном REB-е появлялась строка
    Шаблон <Имя файла>, атрибуты: <длина файла>, <дата файла> <локализованное время файла> <Часовой пояс локализации> (GMT<смещение часового пояса>)
  - созданный DBD-файл получал ту же дату-время модификации, что и исходный файл шаблона
dEbug - режим отладки языкового описания структуры БД. Имеет смысл только если не указан ключ Pattern. В этом случае новая структура БД строится с помощью выполнения программ в DBS-файлах. Данный ключ позволяет включить отладчик этих программ.
N[oCalcVolume] - не проводить оценку требуемого места на диске.
Если данный ключ не указан, REB перед выполнением преобразований данных оценивает свободное место на диске. Предварительно REB вычисляет минимальное и максимальное количество дисковой памяти, необходимое для выполнения работы. Если REB при анализе доступного места на диске обнаруживает, что места точно не хватит, т.е. меньше минимально необходимого, то прекращает работу с соответствующим сообщением и кодом завершения 2.
Если обнаруживает, что места может не хватить, т.е. доступный объем находится в пределах от минимального до максимально необходимого, то
1. в режиме "не по шаблону", т.е. без ключа -Pattern задает вопрос "Для выполнения операции может потребоваться до %dK. Продолжить выполнение?"
2. в режиме "по шаблону", т.е. с ключом -Pattern не задает вопрос, а прекращает работу, как будто пользователь на вопрос "Продолжить выполнение?" ответил отрицательно
В обоих случаях при прекращении работы из-за возможной нехватки места на диске REB возвращает специальный код завершения программы 102. Предполагается, что тот, кто вызывает REB проанализирует этот код завершения и, если, надо вызовет REB повторно с ключом -NoCalcVolume, т.е. "не анализировать место на диске".
NoWaitConnections - не ожидать, когда отключатся все мешающие подключения.
В начале работы REB понимает, какие файлы БД нужно обрабатывать, после чего проверяет есть ли подключения пользователей, имеющих какие-либо права на эти файлы. Если указан ключ NoWaitConnections, то при наличии таких подключений, в том числе и системного, выполняющего переиндексацию файлов БД, работа REB прекращается со специальным кодом завершения 104, и в ERH-файл и в стандартный вывод ошибок (в обычном случае на экран) выводит соответствующее сообщение, в котором перечислены мешающие подключения. Правда, количество подключений в этом сообщении ограничено 10-ю. Если их реально больше 10, то в конце сообщения пишется "и еще N подключений". Без ключа NoWaitConnections в этом случае на консоль клиента выдается сообщение об одном из мешающих подключений, и REB ожидает, когда это подключение будет закрыто. Предполагается, что оператор, выполняющий REB, свяжется с мешающим пользователем и попросит его выйти, или сам выполнит для этого какие-либо действия, воспользовавшись, например, NTF-программой или HTTP-интерфейсом.
W[indowIgnore] - не корректировать видео формы; автоматически включается ключом Pattern. При переходе на клиент-серверную версию (с V14.1.1) не дает эффекта, т.к. собственно работу выполняет серверная часть, а WDO-файлы по факту доступны только из клиентского RED-файла
NoAuth[entication] - диалоги аутентификации запрещены. В случае проблем аутентификации, например при отсутствии прав текущего пользователя на подключение к проекту, REB завершается с кодом 2, а не поднимает диалог с предложением ввести другого пользователя и пароль.
A[bort] - после завершения работы вернуть структуру базы в исходное состояние. REB выполнит всю работу, но в последний момент восстановит исходное состояние проекта. Данный режим можно использовать, как тестовый. REB в этом случае завершается с кодом 103.
InfoHandle:HexHandleValue - 16-ричное значение наследуемого Pipe-Handle-а в который нужно посылать информацию о ходе выполнения.
Это возможность связывать REB с другими программами. Использовать этот ключ при обычном запуске REB невозможно. Он имеет смысл только при вызове REB из программ, которые вызывают его, как порожденную программу. Такая программа может открыть Pipe, причем с разрешением наследования порожденными программами. Затем она может вызвать REB с ключом InfoHandle, указав в параметре значение HANDLE-а этого Pipe-а в текстовом виде в 16-ричном формате. Если такой ключ определен, REB проверяет, что указанное в параметре значение - это действительно открытый Pipe. Если это не так, работа REB прекращается с выдачей Help-сообщения и кодом завершения 2. Если Pipe в норме, то REB посылает в него информацию в следующем формате:
1. Запрос продолжительный, предполагающий выдачу процента выполнения
  1. BYTE 254
  2. <Строка>-заголовок
  3. { BYTE } последовательность байт со значениями от 0 до 100 - это процент выполнения этапа (стадии). Нет гарантии, что последнее значение будет 100. Заканчивается запрос началом нового запроса.
2. Запрос продолжительный, предполагающий периодическое извещение о собственной работе, т.е. "еще жив"
  1. BYTE 253
  2. <Строка>-заголовок
  3. { BYTE с некоторым значением <= 100 (в V14.34.12 это всегда 0)} Последовательность байт - это периодическое сообщение о течении этапа (стадии). Заканчивается запрос началом нового запроса
3. Запрос разовый - информация о причине аварийного завершения работы REB
  1. BYTE 252
  2. <Строка>-текст сообщения.
4. Запрос разовый - уведомление об успешном завершении собственно перестройки структуры БД. На следующих этапах работы тоже возможны ошибки, и код завершения программы REB может быть не 0, но структура БД уже перестроена и никуда не денется, даже если в дальнейшем возникнет какая-нибудь ошибка.
  1. BYTE 250
Строка ::= <DWORD - число байтов в строке, включая '\0'> <указанное число байтов, содержащее текст строки>
Сам формат предполагает любое количество чередующихся запросов 1 и 2 типа, и возможно запрос 3-го типа в конце работы.
Реально в вышеизложенном формате REB посылает в Pipe отчет о следующих стадиях:
1. Подключение к проекту - запрос 2-го типа
2. Анализ изменений - запрос 2-го типа
3. Преобразование данных - запрос 1-го типа
4. При отсутствии ошибки - запрос 4-го типа. Получение запроса 4-го типа гарантирует, что, во-первых, структура БД уже перестроена, во-вторых, других запросов в данном протоколе больше не будет.
5. Запрос 3-го типа с текстом ошибки выдается в случае следующих ошибок:
  1. REB не смог выполнить захват необходимых файлов базы данных, т.к. их удерживают другие подключения. В этом случае программа завершается с кодом 104
  2. Могло не хватить места на диске при выполнении REB, а могло и хватить. В этом случае программа завершается с кодом 102
B[ackRebuild] - отменить результат работы последнего запуска программы reb. Данный режим является прямой противоположностью нормального. Он доступен только для администраторов или программистов. Вместе с использованием данного ключа имеют смысл только ключи NoWaitConnections и NoAuth. Следует понимать, что в этом режиме выполняется не обратная перестройка структуры БД с преобразованием содержимого файлов БД к той структуре, а полное восстановление состояния проекта, бывшего на момент последнего запуска REB, путем копирования физических файлов, откинутых перед началом выполнения того REB-а. Перечень физических файлов и выполненных с ними во время последнего вызова REB операций, находится в файле <Имя проекта>.RBP, который разыскивается по серверному RED-файлу. Получается, что после выполнения REB с ключом -BackRebuild вся работа с данными, выполненная с момента последнего REB-а, будет забыта. Поэтому, при выполнении REB с ключом -BackRebuild просматривается время модификации всех файлов данных (с расширением ASB и DAP), и если это время не совпадает с указанным в RBP-файле, то оператору задается вопрос "У файла FileName изменились дата/время модификации. Восстанавливать файл? [Y/N]". Перед началом собственно копирования файлов оператору всегда задается вопрос "Last rebuild was completed. Abort last rebuild? [Y/N]". После ответа "Y" восстановить текущее состояние данных проекта будет невозможно.

Чтобы внешняя программа могла прервать работу REB, он создает объект синхронизации типа Event с именем, состоящим из подстрок "Event_Stop_Rebuild_0x" и <16-ричного идентификатора собственного процесса без лидирующих нулей>. Этот Event изначально не сигналит. Если любая внешняя программа откроет этот Event и переведет его в сигнальное состояние, то REB прекратит работу (откатится). Код завершения программы будет 1, в ERH-файл и стандартный вывод ошибок (в обычном случае на экран) попадет текст "Выполнение Rebuild прервано".

Возможные коды завершения программы REB

0 - успешное завершение
1 или 2 - некая фатальная ошибка; с высокой вероятностью структура данных не перестроена, но возможно и перестроена, если ошибка случилась на поздних стадиях
100 - не обнаружено изменения структуры базы данных, никакая работа не выполнялась
101 - ошибка на стадии подключения к БД
102 - могло не хватить места на диске при выполнении REB, а могло и хватить
103 - ошибка преобразования данных при выполнении REB: нарушение уникальности, ошибка преобразование к типу и т.п.
104 - REB не смог выполнить захват необходимых файлов базы данных, т.к. их удерживают другие подключения
105 - нет прав на выполнение REB.

Для выполнения REB надо иметь специальные права.

с ключом -Pattern, т.е. по шаблону, может выполнять только администратор
без ключа -Pattern, т.е. новую структуру строить на основе DBS-файлов, может выполнять только программист
с ключом -BackRebuild, т.е. откат последнего выполненного REB, может выполнять только администратор или программист

Если создается новое немассивовое поле NEW, имя которого совпадает с будущим именем существовавшего (массивового) поля WAS, то поле NEW заполняется значением соответствующего элемента массива поля WAS.

Утилита REB в начале своей работы ожидает, пока в проекте не останется ни одного подключения. Новые подключения к проекту на протяжении всей работы REB запрещены - пользователь получает соответствующее сообщение типа "ждите". Исключение составляет пользователь, запустивший REB на выполнение - ему разрешено подключаться к проекту до момента, пока в проекте имеется хотя бы одно подключение (не считая самого REB).