Сценарии *.gcp
Сценарий — текстовый файл с расширением .gcp, по одной команде в строке.
Пустые строки пропускаются.
Запуск
Gamma.exe C:\Scenarios\Calculate.gcp
Приложение выполнит сценарий без показа главного окна и закроется само. Тот же файл можно открыть из окна командного процессора — тогда он выполнится в уже запущенном приложении.
Начинайте сценарий с Mode Set, а не с Mode Get. У свежего процесса режим
ещё не выбран, и Mode Get в этом случае отвечает отказом «режим не выбран» —
то есть останавливает сценарий с кодом возврата 3.
Код возврата
| Код | Значение |
|---|---|
0 | сценарий выполнен до конца |
2 | сценарий не выполнялся: файла нет, он не открылся, пуст или в нечитаемой кодировке |
3 | сценарий начал выполняться, но прервался: команда вернула неуспех либо Break IfVariableIsNotDefined не нашёл переменную |
Gamma.exe scenario.gcp
if %errorlevel% neq 0 (
echo [ERROR] сценарий завершился с кодом %errorlevel%
exit /b 1
)
Выполнение останавливается на первой неуспешной команде — остаток файла не выполняется.
Кодировка файла
Файл должен быть в Unicode. Однобайтовые кодировки (ANSI / Windows-1251) не
поддерживаются — такой файл не выполнится, и приложение вернёт код 2.
Кодировка определяется по содержимому файла, и BOM нужен не всем вариантам:
| Кодировка | Читается |
|---|---|
| UTF-8, с BOM и без | да |
| UTF-16 LE, с BOM и без | да |
| UTF-16 BE с BOM | да |
| UTF-16 BE без BOM | нет |
| UTF-32 (LE и BE) с BOM | да |
| UTF-32 без BOM | нет |
| ANSI / Windows-1251 с не-ASCII | нет |
Вариант без BOM, который не распознан, читается как мусор: сценарий формально
запускается, но первая же строка не совпадает ни с одной командой, и прогон
заканчивается кодом 3, а не 2.
Чисто ASCII-файл в ANSI выполнится: его байты совпадают с UTF-8. Но первый же русский комментарий сделает файл нечитаемым. Сохраняйте сценарии в UTF-8 или UTF-16 LE.
Кодировка выгружаемых файлов
Всё, что командный процессор пишет, пишется в кодировке, которая нужна тому, кто это читает:
| Что | Команда | Кодировка |
|---|---|---|
| настройки | Preferences Export, FEMSolverSettings Export, ExportValue | UTF-8 |
| версия | Version <путь> | UTF-8 |
| журнал команд | CommandProcessorLog Export | UTF-16 |
| журнал приложения | Log Export | UTF-16 |
| переменная окружения | EnvVariable Export | OEM (её читает cmd.exe) |
Менять это обычно не нужно. Если файл забирает инструмент со своими
требованиями, кодировку можно назвать явно — ключом Encoding= одним токеном,
до или после пути:
Preferences Export Encoding=UTF-16 "C:\Work\prefs.txt"
EnvVariable Export Encoding=UTF-8 MY_VAR "C:\Work\env.cmd"
CommandProcessorLog Export Encoding=UTF-8 "C:\Work\log.txt"
Списки допустимых значений у команд разные — предлагается только то, что их
читатель действительно понимает; полный список см. на странице команды.
UTF-16 у EnvVariable Export поэтому недоступен: файл исполняет cmd.exe,
а широкие кодировки он не читает.
Кроме неизвестного значения отвергается и содержимое, которое выбранная кодировка не представляет — с перечислением символов; файл при этом не создаётся, вместо того чтобы записаться со знаками вопроса. Широкие кодировки всегда пишутся с BOM, иначе файл не прочитать обратно (см. таблицу выше).
Самая безопасная комбинация для переноса между машинами — NoTranslation с
кодировкой по умолчанию: содержимое становится латинским, и представить его
может любая кодировка.
Чтение файлов: кодировка определяется сама
Preferences Import, FEMSolverSettings Import и парные им ImportValue
определяют кодировку файла так же, как это делается для .gcp выше, с
откатом на однобайтовую кодовую страницу системы — файл без BOM, сохранённый
в кодировке системы, тоже читается.
Выбор кодировки есть только у *.txt. *.json всегда UTF-8 — его
читатель другого не принимает, — а *.ini пишет QSettings; ключ
Encoding= с этими двумя расширениями отвечает отказом.
Импорт *.txt, который не применил ни одной строки, считается неуспешным —
команда отвечает отказом, и сценарий останавливается с кодом возврата 3. Так
получается с файлом, прочитанным не той кодировкой: он превращается в набор
нераспознанных строк. Пустой файл по той же причине тоже ошибка.
Синтаксис строки
- токены разделяются пробелами;
- кавычки (одинарные и двойные) группируют токен и снимаются при разборе — так передаются пути с пробелами;
- круглые скобки тоже группируют, но остаются частью значения — так
задаётся точка в командах
Geometry; - регистр имён команд, субкоманд и флагов не важен;
- часть необязательных параметров задаётся не по позиции, а по имени — одним
токеном
ключ=значение, в любом порядке после обязательных аргументов (user=johnуFTP,Encoding=UTF-8у экспортов). Ключ принимается и латиницей, и в переводе — как и имена самих команд.
Project Open "C:\Мои проекты\Фильтр.gma"
Geometry Create Box b1 (0 0 0) 10 5 2
Комментарии и остановка
| Команда | Действие |
|---|---|
REM текст | комментарий, строка игнорируется целиком |
ECHO текст | вывести текст в журнал |
Break IfVariableIsNotDefined ИМЯ | прервать сценарий, если переменная не задана |
Break — способ проверить входные условия до первого действия. Условная форма
(Break IfVariableIsNotDefined ИМЯ) при незаданной переменной останавливает
сценарий и даёт код возврата 3. Безусловный Break даёт 0 — он
просто останавливает сценарий, и это считается выполнением.
В TCP/JSON и в Python Break соединение не разрывает: там нет сценария,
который можно прервать. Соединение закрывает только Exit — вместе со
всем приложением.
Переменные
В любой строке шаблон %ИМЯ% заменяется значением переменной: сначала ищется
внутренняя переменная командного процессора, затем переменная окружения. Если
переменной нет, шаблон остаётся в строке как есть — это и ловит Break.
| Команда | Действие |
|---|---|
SET ИМЯ=значение | внутренняя переменная сценария |
EnvVariable Set ИМЯ значение | переменная окружения процесса |
EnvVariable Export ИМЯ путь.cmd | выгрузить переменную в .cmd для вызывающего процесса |
Дочерний процесс не может изменить окружение родителя, поэтому EnvVariable Export пишет .cmd-файл, который вызывающий батник затем исполняет через
call — так сценарий возвращает значения наружу. Файл пишется в OEM-кодировке,
той самой, в которой cmd.exe читает батники, поэтому значение с русскими
буквами возвращается наружу без искажений.
Значение переменной ограничено однобайтовой кодовой страницей системы: его
хранит окружение процесса, а оно на Windows однобайтовое. Символ, которого в
этой странице нет, командой EnvVariable Set не принимается — она отвечает
отказом с перечислением таких символов, а не записывает их искажёнными.
Break IfVariableIsNotDefined PROJECT_DIR
SET EXPORT_DIR=%PROJECT_DIR%\Export
Directory Create "%EXPORT_DIR%"
Project Open "%PROJECT_DIR%\Filter.gma"
Ключи командной строки
| Ключ | Назначение |
|---|---|
<файл>.gcp | выполнить сценарий и закрыть приложение |
<файл>.gma | открыть проект |
/Version <файл> | записать версию в файл |
Дальше
Готовые сценарии целиком — в разделе Примеры.