Библиотека для поддержки автоматизации на основе MS-DOS скриптов

wait.mds

НАЗНАЧЕНИЕ БИБЛИОТЕКИ

Библиотека wait.mds — это средство поддержки автоматизации на основе скриптов MS-DOS. Весь спектр функциональности библиотеки содержится в файле «wait.mds.bat», который может быть использован как исполняемый файл для вызова из любой локальной папки, а также как инсталлятор для установки и регистрации библиотеки. Исходный файл библиотеки и сопутствующие к ней файлы доступны по ссылке проекта: https://github.com/kopyurff/wait.mds.

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

УСТАНОВЩИК БИБЛИОТЕКИ

Файл библиотеки "wait.mds.bat" для своего использования в общем случае не требует предварительной установки программного обеспечения на ОС Windows всех версий от XP до 11 и может использоваться как есть на любой машине. При вызове пользователем элементов функциональности библиотеки требуемая установка производится автоматически в фоновом режиме. Исключением является обязательная предварительная установка Microsoft .NET Framework 3.5 SP1 на Windows XP, поскольку эта ОС не имеет предустановленного фреймворка. Также для работы консольных приложений должна быть настроена система безопасности ОС. Если эти настройки не были выполнены, то их следует либо выполнить вручную, либо запустить установщик для автоматической настройки:

call wait.mds.bat /sub:install /install /all

Если ОС нуждалась в ручной или автоматической настройке параметров, то для их вступления в силу необходимо перезагрузить компьютер. Если вы производите установку, то для ее завершения вам потребуется запустить ее снова после перезагрузки. В результате полной установки в папке %ProgramFiles% будет создан подкаталог "wait.mds", в котором будут находиться: копия оригинального файла библиотеки; облегченная версия библиотеки в файле "wait.mds.lite.bat"; файл справки HTML; текстовый файл в кодировке консоли со счетчиками производительности для утилиты "typeperf.exe"; скомпилированные и зарегистрированные файлы COM-сервера (x86/x64 в зависимости от разрядности ОС); исходный код COM-сервера на VB.NET и вспомогательный файл на VBScript из установщика. Также регистрируется переменная окружения %wait.mds% для запуска библиотеки "wait.mds.lite.bat" из любой папки и создается ярлык на рабочем столе для файла справки HTML, который также можно открыть с помощью клавиш "Ctrl-Alt-Shift-W".

Помимо ключа "/all", также возможна установка только COM-сервера с помощью ключа "/vb", установка только счетчиков производительности с помощью ключа "/tpc", а также установка с помощью ключа "/lib", который выполняет все действия из полной установки, за исключением действий при установках с двумя предыдущими ключами.

ВЫЗОВЫ ВНУТРЕННИХ ПРОЦЕДУР

Внешний вызов внутренних библиотечных процедур реализуется через форматированную строку первого аргумента, содержащую префиксную подстроку "/sub:" и суффиксную подстроку, содержащую имя процедуры. Следующие аргументы являются аргументами внутренних процедур. Основными процедурами являются процедура установщика, а также процедуры "importMacros" и "unsetMacros" для загрузки и выгрузки определений макросов из контекста пакетного файла пользователя. Установленная версия библиотеки "wait.mds.lite.bat" не имеет процедуры установщика. Полное описание внешних процедур приведено в HTML-файле справки установленной библиотеки.

ОБРАБОТКА СОБЫТИЙ

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

ИМПОРТИРУЕМЫЕ МАКРОСЫ БИБЛИОТЕКИ

Определения макросов импортируются в контекст пакетного файла пользователя с помощью вызова процедуры библиотеки. Их полное описание приведено в файле справки HTML, который генерируется установщиком. Список определений макросов библиотеки:

@errorLevel - устанавливает уровень ошибки, равный цифровому значению;
@isok - проверка корректности импорта определений;
@exit - выход из стека вызовов файлов и процедур;
@error - сообщает об ошибке и завершает выполнение скрипта;
@echo_imprint - печатает текст в одной той же строке консоли;
@imprintxy - печатает текст со сдвигом строки и столбца;
@drop_conrows - очищает указанное количество последних строк консоли;
@mac_wrapper - запуск макроса и возврат его результата;
@mac_wraperc - запуск макроса и возврат его результата;
@mac_check & @istrue - запуск макроса и установка уровня ошибки;
@spinner - запускает цикл до указанного таймаута в мсек;
@mac_spinner - запускает цикл, пока макрос не завершит работу;
@mac_loop & @mac_do - цикл под управлением макроса с телом цикла;
@unset - удаляет определения переменных, очищая их значения;
@unset_mac - удаляет определения макросов;
@unset_alev - удаляет переменные окружения;
@runapp - запускает новое приложение с помощью команды `start`;
@chcp_file - перекодирует текст файла из одной кодовой страницы в другую;
@str_length - вычисляет длину строки;
@str_unquote - удаляет все кавычки в строке;
@fixedpath - ищет и получает полный путь объекта на диске;
@shortpath - преобразует строку пути объекта в строку имен DOS "8.3";
@get_number - устанавливает числовое значение переменной;
@get_xnumber - числовое значение переменной (x16 -> x10);
@rand - генерирует случайное число в заданном диапазоне;
@echo_params - выводит список параметров;
@enumA & @enumB - печать результата 'for-in-do' одного за другим;
@ipaddress - локальный IP-адрес;
@web_avail - проверяет, доступно ли подключение к Интернету;
@web_ip - возвращает локальный IP-адрес подключения к Интернету;
@regvalue - значение из реестра Windows в кодовой странице консоли;
@shellfolder - полные пути к специальным папкам;
@oemtocp - перекодировка из OEM Windows в кодовую страницу консоли;
@cptooem - перекодировка из кодовой страницы консоли в OEM Windows;
@str_decode - заменяет псевдотеги с кодами на символы строки;
@syms_replace - заменяет все вхождения символов на другие символы;
@sym_replace - заменяет все вхождения символа на другой символ;
@syms_cutstr - получает подстроки между символом(ами);
@pid_title - возвращает заголовок окна процесса с заданным PID;
@title - получает заголовок окна или идентификатор процесса (PID);
@title_pid - находит PID окна, используя подстроку заголовка;
@substr_remove - удаляет подстроки внутри разделителей;
@substr_get - вывод строки из подстрок внутри разделителей;
@substr_extract - вывод подстрок внутри заданных разделителей;
@substr_regex - подстрока символов, соответствующих регулярному выражению;
@str_trim - очищает начальные и конечные символы;
@str_encode - замена управляющих символов на их ASCII коды;
@str_clean - удаляет выбранные наборы символов из строки;
@str_plate - перезаписывает выбранные наборы символов;
@str_arrange - реорганизация подстрок в строке;
@str_upper - преобразует строку в верхний регистр букв;
@str_isempty - проверяет, является ли параметр пустым;
@date_span - временной промежуток дат и времени формата WMIC;
@time_span - извлекает значения времени из строки времени;
@obj_attrib - считывает атрибуты файла или папки на диске, их изменение;
@obj_size - получает данные о размере файла или папки на диске;
@disk_space - общее, свободное и используемое пространство диска;
@exist - проверяет наличие объекта на диске;
@exist_check - проверка наличия объекта и работоспособности диска;
@obj_newname - новое имя в указанном месте для нового объекта;
@perf_counter - получает локализованный счетчик typeperf.exe;
@typeperf - возвращает результат запроса typeperf.exe.
@typeperf_devs - возвращает список устройств с запроса typeperf.exe;
@typeperf_res_a - определяет использование устройства по двум счетчикам;
@typeperf_res_b - определяет использование устройства;
@typeperf_res_c - определяет использование устройства по двум счетчикам;
@typeperf_res_d - определяет использование устройства;
@typeperf_res_use - использование устройств по их прошитым типам;
@nicconfig - находит сетевое устройство и возвращает его данные;
@netdevs - возвращает CSV-списки основных свойств сетевых устройств;
@res_select - выполняет задачу и выбирает элементы ее результата;
@event_file - добавляет или удаляет запись из файла событий;
@event_item - получает указанный атрибут события с идентификатором;
@runapp_getpid - запускает приложение и возвращает его PID;
@sleep_wsh - остановка вызывающего процесса на несколько миллисекунд;
@runapp_wsh - запуск приложения с помощью объекта `WScript.Shell`;
@sendkeys - отправка нажатий клавиш клавиатуры в активное окно;
@shortcut - создает ярлык Windows указанного объекта;
@hex - преобразует десятичное число в шестнадцатеричную строку;
@taskinfo - возвращает сведения о процессе;
@procpriority - считывает или устанавливает приоритет процесса;
@findwindow - находит окно, используя имя класса окна и его заголовок;
@windowstate - проверяет состояние заданного атрибута окна;
@activewindow - возвращает дескриптор текущего активного окна;
@foregroundwindow - возвращает дескриптор окна переднего плана;
@windowclass - возвращает класс окна с указанным дескриптором;
@windowcaptext - возвращает заголовок окна с указанным дескриптором;
@windowrect - возвращает прямоугольник клиентской области окна;
@showwindow - показывает окно в соответствии с заданной командой;
@findshow - находит окно по именам класса и заголовка, показывает его;
@movewindow - перемещает окно в точку в абсолютных координатах;
@sendmessage - отправляет сообщение окну с указанным дескриптором;
@findcontrol - находит дочернее окно родительского окна;
@closewindow - закрывает или сворачивает окно;
@showdesktop - макрос сворачивает все окна и показывает рабочий стол;
@repaint - перерисовывает указанное окно или рабочий стол;
@windowsofpid - возвращает дескрипторы окон процесса с указанным PID;
@pidofwindow - возвращает PID процесса окна с указанным дескриптором;
@coprocess - возвращает PID дочернего или родительского процесса;
@screenshot - делает снимок экрана окна или экрана и сохраняет его в файл;
@compareshots - побайтовое сравнение данных двух снимков экрана;
@cursorpos - получение или изменение абсолютных координат указателя мыши;
@mouseclick - эмулирует нажатие кнопки мыши;
@monitor - возвращает идентификатор монитора;
@appbarect - возвращает прямоугольник панели задач Windows;
@screenrect - возвращает прямоугольник клиентской области монитора;
@screensize - получение или изменение разрешения экрана монитора;
@movetoscreen - перемещает окно в клиентскую область монитора;
@consoletext - считывает текст указанного консольного окна;
@shrink - сжатие данных, поддерживает строковое представление сжатых данных;
@comparefiles - выполняет побайтовое сравнение данных двух файлов;
@environset - выводит все переменные среды процесса консоли;
@enwalue - получает переменную среды из процесса `cmd.exe`;
@radix - преобразует числа из одной системы счисления в другую;
@code - кодирует строку в последовательность 16-ых кодов символов;
@callstack - возвращает текущий стек вызовов в указанном `cmd.exe`.

НАБОР ДОПОЛНИТЕЛЬНЫХ ФАЙЛОВ ПРОЕКТА БИБЛИОТЕКИ

Проект библиотеки находится по ссылке, указанной в начале этого описания. В проект библиотеки wait.mds были добавлены дополнительные файлы для лучшего соответствия критериям программного обеспечения с открытым исходным кодом, для документирования устанавливаемых компонентов и, при необходимости, для упрощения работы с исходным кодом. Например, развернутое определение макроса можно временно переместить в локальный файл пользователя для трассировки или использовать для изучения исходного кода библиотеки. Список файлов с их относительным расположением:

".\docs\Назначение и сигнатуры COM-функций библиотеки wait.mds.pdf" - описание COM сервера на русском языке;
".\docs\Purpose and signatures of COM functions of the wait.mds library.pdf" - описание COM сервера на английском языке;
".\macros\macros.general.collapsed.bat" - полный список свёрнутых определений макросов общего назначения;
".\macros\macros.general.expanded.bat" - полный список развернутых определений макросов общего назначения;
".\macros\macros.special.expanded.bat" - полный список определений макросов, которые используются внутри библиотеки, а также определений макросов, которые представлены в виде переработанных строк внутри макросов общего назначения;
".\tests\wait.mds.tests.macros.bat" - полный набор тестов для макросов общего назначения. В дополнение к полному перечню тестов макросов, он также является списком примеров их использования;
".\tests\call.stack.test\.." - подпапка, используемая тестами макросов общего назначения;
".\tests\call.stack.test\dir 4\test-stack-4.bat" - содержит тест и пример использования макроса @callstack;
".\tests\wait.mds.tests.events.bat" - полный список тестов обработки событий;
".\tests\wait.events.json" - файл в формате JSON, используемый для тестирования обработки событий и макросов;
".\tests\wait.mds.tests.subroutine.bat" - тестирование внешней процедуры;
".\tests\wait.mds.samples.installer.bat" - тестирование установщика;
".\tests\wait.mds.samples.events-mymacro.bat" - пример преобразования простого макроса в строку, которую можно включить в файл событий JSON;
".\com.api.wrapper\test_batch.bat" - тестовый скрипт, который используется тестами;
".\com.api.wrapper\test_forms.exe" - тестовое приложение, используемое тестами. Оно откомпилировано с использованием Microsoft .NET Framework 3.5 SP1 и в более поздних версиях ОС фреймворк необходимо будет установить локально, если он не установлен;
".\com.api.wrapper\- wds.source -\wait.mds.injector.cpp" - исходный файл динамической библиотеки инжектора на языке Си, которая используется для чтения текста консоли. В исходном коде COM сервера скомпилированные 32-х и 64-битные версии инжектора представлены в виде свернутых строк;
".\docs\Общее описание библиотеки wait.mds.pdf" - общее описание библиотеки на русском языке;
".\docs\General description of the wait.mds library.pdf" - общее описание библиотеки на английском языке.

СТАТУС ПРОЕКТА, ПОДДЕРЖКА И РАЗВИТИЕ

Исходный код библиотеки работоспособен и может быть использован на версиях ОС Windows от XP до 11. Текущий набор функционала библиотеки формировался в течение нескольких лет для решения тех задач автоматизации, которые возникали лично у меня. Данный функциональный набор публикуется для общего использования как есть. С целью решения других аналогичных задач автоматизации набор возможностей библиотеки может быть расширен или улучшен. Для предложений по поддержке и развитию проекта я доступен по следующим контактам:

E-Mail: kopyurff@yahoo.com, kopyurff@rambler.ru

Мобильный: 8-921-912-44-10