Команды

Условные обозначения

ОбозначениеЗначение
PtТекст
PfИмя файла
PmПоток
PqPQ результат
PoИспользуется для вывода результата
PcСоединение с базой
PjСвязь с ОС
PsСтиль

Отличается от маркировки регистров ввода вывода тем, что Pm может обозначать любой, как входной, так и выходной конец потока. Po перед обозначением типа отмечает факт вывода туда. Pm без Po в выходном регистре ввода-вывода обозначавет, что происходит не вывод в поток, а создание, замена или уничтожение выходного потока соответствующего регистра.

Обозначение Po Pm во входном регистре показывает, что происходит не ввод из потока, а создание, замена или уничтожение входного потока соответствующего регистра.

Обозначение Po перед любым другим типом, по сути, обозначает то же самое - создание указанного типа.

Список команд по состоянию на момент написания

КомандаПараметры
Вывод Управление Ввод База Работы Стиль
OUT CTL IN CON JOB STY
# Если следует после команды с Pq в CTL , то очередное поле к значению Pq Во всех остальных случаях пустая команда, комментарий. Литерал помещается в интерпретируемый код.
#! Для использования в первой строке в виде
#!/usr/local/bin/pgoblin
Во всех остальных отношениях просто комментарий.
#begin Po Pq Pt Pc Если не была начата средствами pgoblin транзакция раньше, то начинается сейчас. Реализовано подачей BEGIN в соединение, указанное в CON , если не было сделано раньше. Может пересекаться с прямым употреблением END в версиях СУБД, не допускающих вложения транзакций. Вложенные пары #begin - #end не порождают вложенных BEGIN - END в соединении с базой. Предназначено для реализации транзакций при неопределенности в наличии уже начатой транзакции, нужно было у старых версий PostgreSQL. Если регистр OUT не 0 , то содержит структуру, у которой можно спрашивать об ошибке.
#binpresel Po Pq Pq Pt Pc Запрос в CTL помещает двоичный результат в OUT.
#binselect Po Pm Pt Pc Ps Запрос в CTL выдает потоковый двоичный результат в OUT с использованием STY.
#call
#cat Po Pf Pt Ps Если регистр STY 0 , то в OUT помещается файл, чье имя задано в CTL , иначе файл, чье имя задано в секции из регистра STY , чье имя задано в CTL . При помещении имени файла в регистр какие либо действия над файлом не производятся, в том числе не проверяется его наличие. Если в дальнейшем произойдет обращение к этому регистру для вывода, то файл будет создан или дописан к существующему, если существовал до того. Если будет обращение для ввода, файл будет открыт в поток.
#clear Po Pt Po Pj Po Ps Освобождает JOB и STY , если не 0 . 0 ые JOB и STY не меняются. Так же очищает не 0 й OUT , если там нет Po|Pm.
#close Pm Po Pm Po Pc Po Ps Закрывает выходной поток OUT , входной поток IN , стиль STY и соединение с базой CON . Использовать один и тот же регистр для IN и OUT можно. Потоки и соединение с базой 0х регистров не закрываются. В указанном CON , если не 0 , сбрасывается флаг, который запрещает автоматически закрывать соединение с базой по окончании процесса.
#connect Pt Po Pc Подключает базу, заданную в CTL к регистру базы, заданному в CON . CTL должен содержать разрешенное имя СУБД, после которого может быть пробел и другой текст. Интерпретация текста после имени СУБД зависит от конкретной СУБД, обычно там может располагаться имя сервера, имя базы и т.п.
#copyin Po Pq Pt Pm Pc Из IN данные потребляются запросом в CTL в формате COPY . Если регистр OUT не 0, то содержит структуру, у которой можно спрашивать об ошибке.
#copyout Po Pm Pt Pc Запрос в CTL выдает данные в OUT в формате COPY
#display Po Pm Pq Ps IN в формате Pq помещается в OUT в потоковом формате с применением STY.
#echo Po Pt Pt Ps Если регистр STY 0, то в OUT выводится все содержимое CTL, иначе в OUT выводится секция из регистра STY , чье имя задано в CTL .
#end Po Pq Pt Pc Если транзакция была раньше начата соответствующей #begin , то прекращается сейчас, иначе только считается уровень вложенности. Реализовано подачей при необходимости END в соединение, указанное в CON . Может пересекаться с прямым употреблением END в СУБД, не допускающих вложения транзакций. Если регистр OUT не 0 , то содержит структуру, у которой можно спрашивать об ошибке.
#eval Pt Pq CTL исполняется как программа на pgoblin . Контекст при этом включает в точности те же самые регистры, но может установить собственный #trap . Если собственный #trap исполняемым текстом не установлен, при ошибке выполнение этого текста прекращается и ищется #trap в вызвавшем уровне. Если собственный #trap текстом устанавливается, то действует только на текущий уровень и по завершении этого уровня удаляется. Если IN не 0 , то CTL исполняется для каждого кортежа регистра IN , при этом каждый прогон исполняемой программы видит только свой кортеж. В частности, если кортежей в IN нет, то CTL не исполнится ни разу.
#exec Po Pm Pq Pm Pj Запускаются на выполнение в JOB программы, содержащиеся в строках CTL , по одному процессу на каждую строку Pq из CTL . stdin и stdout для запускаемых программ задаются в IN и OUT . Запуск осуществляется под управлением и по правилам заданного регистра JOB . Предполагается, что первое поле определяет имя вызываемой программы, остальные поля - аргументы. NULL значения при подготовке вызова не участвуют ни в рассчете позиций имя программы/номер аргумента, ни в подготовке вызова.
#exit Pt Po Pc Завершение исполняемого процесса. Так же служит признаком конца секции при синтаксическом разборе. При использовании библиотеки вызывает окончание всего процесса, в котором использовался интерпретатор. Если такое поведение нежелательно, то для завершения интерапретации надо использовать #return . Если указан не 0 й регистр CON , то закрываются не все соединения с базой, разрешенные для автоматического закрытия, а только соединение из указанного регистра, при этом флаг запрета автоматического закрытия при выходе не имеет значения. Если CTL не пуст, то в нем должно быть число в тексте - код возврата.
#file Po Pf Pt Ps Если регистр STY 0 , то в OUT помещается файл, чье имя задано в CTL , иначе файл, чье имя задано в секции из региста STY , чье имя задано в CTL . При помещении имени файла в регистр какие либо действия над файлом не производятся, в том числе не проверяется его наличие. Если в дальнейшем произойдет обращение к этому регистру для вывода, то файл будет создан или обнулен, если существовал до того. Если будет обращение для ввода, файл будет открыт в поток.
#fork Po Pm Pq Pm Pj pgoblin форкается, ребенок исполняет команды сразу после #fork до #exit или #return , родитель выполняет команды, расположенные после последней команды ребенка. У ребенка во всех открытых регистрах базы ставится отметка, запрещающая автоматическое закрытие при выходе. Поскольку все соединения у родителя и ребенка общие, это защита родителя от закрытия соединений с базой при окончании ребенка. На случай окончания родителя раньше ребенка того стоит готовить к этому специальным образом, что бы ребенок использовал только собственные соединения. Вывод OUT регистра в ребенке есть ввод этого же регистра в родителе, и ввод IN регистра в ребенке есть вывод этого же регистра в родителе, остальные регистры общие. Если CTL не 0 , то порождается столько процессов, сколько кортежей в CTL , и в каждом ребенке в регистре CTL доступно ровно по одному кортежу от исходного CTL .
#getarg Po Pm Pt Pj В OUT помещается поток в формате COPY с 2мя колонками:
  1. - номер аргумента, начиная с 0
  2. - значение аргумента
Если CTL пуст, или перед употреблением #getarg не употреблялся #getopt , то аргументы выдаются, начиная с первого после конца флагов и параметров флагов у вызова pgoblin , которым запущен скрипт. После употребления #getopt из CTL , если он есть, читается количество аргументов, которые надо получить из командной строки. Не полученные аргументы могут быть флагами, которые можно получить последующим вызовом #getopt .
#getcsv Po Pm Pt Pm Pj Преобразует CSV вход в COPY выход. В CTL содержатся в первых 2х байтах символ запятой и символ кавычки, далее может следовать неотрицательное целое число, к которому насильно будет приводиться количество колонок на выходе, обрезанием лишних или добавлением NULL для недостающих. Если число не задано, то в каждой строке выводится ровно столько значений, сколько есть в соответствующей записи исходника. Если CTL отсутсвует, то для запятой принимается символ ';', а для кавычки символ '"'.
#getdir Po Pm Pt Pq Pj В CTL содержится целое число в тексте, представляющее из себя битовую маску. Если IN 0, то после этого числа ровно 1 пробел и имя каталога для листинга, иначе имя берется из IN. В OUT выводятся колонки в формате COPY по маске:
  • - 0x01 номер строки по порядку, начиная с 0
  • - 0x02 имя файла
  • - 0x04 размер файла
  • - 0x08 mode объекта
  • - 0x10 uid объекта
  • - 0x20 gid объекта
#getenv Po Pm Pj В OUT помещается поток в формате COPY с 3мя колонками:
  1. - номер строки по порядку, начиная с 0
  2. - имя переменной окружения
  3. - ее значение
#getget Po Pm Pj В OUT помещается поток в формате COPY с 3мя колонками:
  1. - номер строки по порядку, начиная с 0
  2. - имя аргумента запроса HTTP GET
  3. - его значение
Эта команда предназначена для реализации CGI , метод GET , подробности в мане getCGIparm.
#getjob Po Pm Pj В OUT помещается поток в формате COPY с 4мя колонками:
  1. - номер строки по порядку, начиная с 0
  2. - номер команды, которая породила этот процесс
  3. - PID процесса
  4. - статус процесса
для всех процессов в заданном JOB . Сам #getjob выполняется в JOB 0 .
#getmeta Po Pm Pq В OUT помещается поток с именами и типами полей IN Pq в формате COPY с 7ю колонками:
  1. - номер поля, начиная с 0
  2. - имя поля
  3. - тип поля
  4. - модификатор типа
  5. - длинна поля (обычно внутренняя, зависит от СУБД)
  6. NULL
  7. NULL
В зависимости от содержимого IN имена и типы могут содержать NULL. две последние колонки с NULL предназначены для будущих расширений.
#getopt Po Pm Pt Pj В OUT помещается поток с аргументами скрипта в формате COPY с 3мя колонками:
  1. - номер по порядку
  2. - флаг
  3. - аргументы флага в text[], или NULL, если флаг не описан.
В CTL содержится цифра, один пробел и строка, описывающая опции в формате babolo_setopts (3) . Цифра в начале строки задает флаг Bpars_NONU , 1 - флаг установлен, 0 - сброшен. Кроме того, установлены флаги Bpars_SYME | Bpars_ESYM | Bpars_EPRM и symr установлен в Z
#getpost Po Pm Pm Pj В OUT помещается поток в формате COPY с 3мя колонками:
  1. - номер строки по порядку, начиная с 0
  2. - имя аргумента запроса HTTP POST
  3. - его значение
Информация для команды берется из IN . Эта команда предназначена для реализации CGI , метод POST , подробности в мане getCGIparm.
#getproc Po Pm Pj В OUT помещается поток в формате COPY с 3мя колонками:
  1. - PID процесса
  2. - номер аргумента, начиная с 0
  3. - значение аргумента
для всех процессов в системе. Источником служит /proc/.
#getspq
#getstr Po Pm Pm Pj Если CTL пуст, то в OUT помещается поток с 2мя колонками в формате COPY
  1. номер строки по порядку, начиная с 0
  2. содержимое строки
Строки берутся из входного потока IN. Поведение при непустом CTL пока не определено.
#info Po Pq Pq
#job Pt Pj Подкючает интерфейс ОС, заданный в CTL , к указанному регистру JOB . CTL должен содержать имя разрешенного интерфейса, после которого может быть пробел и флаги, после возможных флагов может быть число, задающее максимальное количество выполняющихся процессов под управлением этого регистра. Если на заданном регистре JOB уже выполняется максимальное разрешенное количество процессов, то при запуске очередного процесса происходит ожидание окончания одного из них перед запуском следующего. Имеются следующие флаги:
  • -z поднять уровень реакции на ошибку ребенка на 1
  • -Z обнулить уровень реакции на ошибку ребенка
всего есть 3 уровня реакции
  • 0 - не считать ошибку ребенка своей ошибкой
  • 1 - команда #wait завершается ошибкой после сбора всех детей, если хоть один из них кончился ошибкой
  • 2 - сразу после обнаружения окончившегося ошибкой ребенка распространять ошибку далее
по умолчанию уровень реакции 0.
#listen Po Pq Pt Pt Pc Ждет notify с именем, указанным в CTL . Время ожидания не более, чем до указанного в IN . Параметры NOTIFY отдаются в Po , если он не 0.
ВНИМАНИЕ! Время ожидания задается в двоичном виде в целом 64битовом формате с сетевым порядком битов в микросекундах UNIX времени. Может быть получено запросом вида:
#binpresel
SELECT (( date_part('epoch', DateTimeWaitTo)
        + date_part('second', DateTimeWaitTo)
        - floor(date_part('second', DateTimeWaitTo))
        ) * 1000000
       )::int8
ВНИМАНИЕ! Если управление конвертируется из Pq , то там должно быть единственное поле. В противном случае будет несовместимость с будущими версиями.
#perform Po Pq Pq Pt Pq Pc В соединение, заданное CONN , отправляется запрос, заданный CTL . Какого либо вывода не ожидаем. Если указан ненулевой IN , то строки Pq оттуда являются параметрами, с которыми по очереди запускается запрос. Синтаксис определяется используемым CONN . Если аргументом в CTL будет Pt , то запрос в CON посылается один, а если там будет Pq , то из каждой строки в CTL Pq формируется отдельный запрос, от 0 запросов и больше. Не все СУБД понимают параметрическую подстановку, если в запросе больше одной команды. Если регистр OUT не 0, то содержит структуру, у которой можно спрашивать об ошибке.
#pipe Pm Po Pm Связывает выходной поток OUT со входным потоком IN . Использовать один и тот же регистр для входа и выхода можно. 0 й регистр обрабатывается, как и остальные.
#return Po Pc Если процесс был порожден командой #fork , то эта команда эквивалентна #exit без CTL . Если это конец секции #trap , то возврат к следующей за ошибочной команде, при этом CON не используется.
#rollback Po Pq Pt Pc Выполняется ROLLBACK. Если регистр OUT не 0 , то содержит структуру, у которой можно спрашивать об ошибке.
#select Po Pq Pq Pt Pq Pc Запрос в управляющем регистре помещает результат в OUT . Если указан ненулевой IN , то все значения из IN Pq являются параметрами для подстановки в запрос. Синтаксис определяется используемым CONN .
#strselect Po Pm Pt Pc Ps Запрос в CTL выдает потоковый результат в OUT с использованием STY.
#style Pt Pt Ps В заданный регистр STY устанавливается стиль, указанный в CTL , из набора стилей, представленного текстом в IN . В 0 м регистре STY установлен предопредененный стиль, попытка изменить стиль в этом регистре оканчивается ошибкой. В CTL должен быть непустой идентификатор стиля.
#trap Задает секцию, исполняемую после возникновения ошибки, прервавшей нормальное выполнение программы. При нормальном выполнении программы секция, начинающаяся с этой команды и до конца секции ( #return или #exit ) не выполняется, а только запоминается.
#untrap Прекращается действие команды #trap.
#wait Pj Ожидаем окончания всех процессов, запущенных на JOB .

Если в команде указан 0й регистр управления (или он используется неявно) и команда требует Pt, то на управление команде подается литерал команды - тот текст, что расположен между текущей командой и следующей. Этот литерал может отсутствовать, тогда управление пусто.

Если в команде указан 0й регистр управления (или он используется неявно) и команда требует Pq, то команда в качестве входных данных употребляет свой текстовый аргумент и текстовые аргументы всех последующих пустых команд до первой непустой.

Команда #select помещает весь результат запроса в память. Если результат большой и предназначен для вывода (может и в этом же скрипте, если входной регистр Pm), то эффективнее применять команду #strselect. Но если результат применяется в этом же скрипте в виде Pt или Pq, то надо применять команду #select. Если объем вывода предполагается небольшой, то и для вывода эффективнее применять #select, с авторазгрузкой или с выгрузкой при помощи команды #display. В отличие от авторазгрузки при #display можно указать стиль.

В паре команд #binpresel и #binselect примерно такое же разделение труда, но для мелких результатов #binpresel не эффективнее, чем #binselect.

Примеры

Во временную таблицу t помешаем параметры всех процессов системы:

#!/usr/local/bin/pgoblin -Bpgsql
#getproc 2
#perform
CREATE TEMP TABLE t(pid int, argc int, argv text);
#copyin  002
COPY t FROM stdin;
       

Делаем запрос, полученный в результате другого запроса:

#!/usr/local/bin/pgoblin -Bpgsql
#select  2
SELECT 'SELECT * FROM pg_class LIMIT ' || COUNT(*) FROM pg_user;
#strselect 02
       

Для работы примеров нужно право доступа к PostgreSQL с параметрами по умолчанию.


А.А.Бабайлов (C)2003..2022