Создание подсистем, взаимодействующих с SRC

Команды Контроллера системных ресурсов (SRC) - это исполняемые команды, которые получают аргументы из командной строки.

После проверки синтаксиса команды вызываются динамические функции SRC для создания дейтаграммы UDP и ее отправки демону srcmstr.

Дополнительная информация о функциях SRC и их использовании подсистемами для связи с главным процессом SRC приведена в следующих разделах:

Получение подсистемами запросов SRC

Способ получения подсистемой запросов от SRC зависит от выбранного способа обмена данными. Демон srcmstr получает запросы на обработку от процесса команды через сокеты и создает необходимый сокет или очередь сообщений для передачи этого запроса. Подсистема должна проверить, что сокет или очередь сообщений действительно были созданы. Рекомендации по программированию пакетов с запросами SRC для подсистем, применяющих различные способы обмена данными, приведены в следующих разделах:

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

Получение сигналов SRC

В подсистемах, обменивающихся с SRC сигналами, должна быть определена процедура обработки сигналов SIGNORM и SIGFORCE. В ней может использоваться любой метод обработки сигналов. Ниже приведено два примера подобных функций.

Функция Описание
Функции sigaction, sigvec и signal Задают действие, которое должно быть выполнено при получении сигнала.
Функции sigset, sighold, sigrelse и sigignore Предоставляют для прикладных процессов расширенные функции для работы с сигналами и управления ими.

Получение пакетов с запросами SRC через сокеты

Ниже приведены рекомендации по созданию подсистем, получающих пакеты с запросами SRC через сокеты:

  • Включите в программу подсистемы файл /usr/include/spc.h, содержащий структуру подсистемы SRC. Эта структура применяется подсистемой для ответа на команды SRC. Кроме того, файл spc.h содержит файл srcerrno.h, который не нужно указывать особо. Файл srcerrno.h содержит определения ошибок, необходимые для поддержки демона.
  • При запуске подсистемы, применяющей сокеты, дескриптор файла 0 присваивается сокету, через который подсистема получает пакеты с запросами SRC. Подсистема должна убедиться, что этот дескриптор действительно был назначен сокету с помощью функции getsockname, которая возвращает адрес сокета подсистемы. Если дескриптор сокета отличен от 0, подсистема должна занести в протокол сообщение об ошибке и завершить свою работу. Информация о том, как получить адрес сокета подсистемы с помощью функции getsockname приведена в разделе "Пример программы чтения дейтаграммы Internet" в книге Communications Programming Concepts.
  • Если подсистема работает с несколькими сокетами, то с помощью функции select она может определить, в каком из сокетов есть данные. Дополнительная информация по выполнению этой задачи с помощью функции select приведена в разделе "Пример программы проверки ожидающих соединений" в книге Communications Programming Concepts.
  • Для получения пакета с запросом из сокета предназначена функция recvfrom.

    Примечание: Целевой адрес для возврата ответа подсистемы хранится в полученном пакете с запросом SRC. Его не следует путать с адресом, который функция recvfrom возвращает в качестве одного из своих параметров.

    После получения пакета с помощью функции recvfrom можно вызвать функцию srcrrqs, которая возвращает указатель на статическую структуру srchdr. Этот указатель позволяет получить адрес, по которому нужно отправить ответ подсистемы. Эта структура переопределяется при каждом вызове функции srcrrqs, поэтому ее нужно сохранить в некоторой переменной, если она еще потребуется после следующего вызова srcrrqs.

Получение пакетов с запросами SRC с помощью очереди сообщений

Ниже приведены рекомендации по созданию подсистем, получающих пакеты с запросами SRC из очередей сообщений:

  • Включите в программу подсистемы файл /usr/include/spc.h, содержащий структуру подсистемы SRC. Эта структура применяется подсистемой для ответа на команды SRC. Кроме того, файл spc.h содержит файл srcerrno.h, который не нужно указывать особо. Файл srcerrno.h содержит определения ошибок, необходимые для поддержки демона.
  • Укажите при компиляции опцию -DSRCBYQUEUE. В результате поле типа сообщения (mtype) станет первым в структуре srcreq. Эта структура применяется при получении пакетов SRC.
  • После запуска подсистемы необходимо выполнить функцию msgget и проверить, что во время запуска была создана очередь сообщений. Если она не была создана, подсистема должна занести в протокол сообщение об ошибке и завершить работу.
  • Если подсистема работает с несколькими очередями сообщений, то с помощью функции select она может определить, в какой из очередей есть данные. Дополнительная информация по выполнению этой задачи с помощью функции select приведена в разделе "Пример программы проверки ожидающих соединений" в книге Communications Programming Concepts.
  • Для получения пакета из очереди сообщений предназначены функции msgrcv и msgxrcv. Адрес, по которому подсистема должна отправить пакет с ответом, указан в полученном пакете.
  • После получения пакета с помощью функции msgrcv или msgxrcv вызовите функцию srcrrqs. Эта функция возвращает указатель на статическую структуру srchdr, которая переопределяется при каждом вызове функции srcrrqs. Этот указатель позволяет получить адрес, по которому нужно отправить ответ подсистемы.

Обработка подсистемами пакетов с запросами SRC

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

Обработка пакета с запросом разбивается на два этапа:

Чтение пакета с запросом SRC

Подсистема получает пакет с запросом SRC в виде структуры srcreq, описанной в файле /usr/include/spc.h. Запрос подсистемы расположен в структуре subreq, вложенной в структуру srcreq:

struct subreq
      short object;         /*объект для обработки*/
      short action;         /*действие START, STOP, STATUS, TRACE,\
                             REFRESH*/
      short parm1; /*зарезервировано для переменных*/
      short parm2; /*зарезервировано для переменных*/
      char objname; /*имя объекта*/

Поле object структуры subreq задает объект, над которым нужно выполнить действие. Если запрос относится к подсистеме, в поле object указывается константа SUBSYSTEM. В противном случае в поле object указывается кодовый знак, либо в поле objname указывается PID субсервера в виде символьной строки. Ответственность за правильный выбор объекта, к которому относится запрос, ложится на подсистему.

Поле action задает запрошенное действие над подсистемой. Все подсистемы должны поддерживать действия START, STOP и STATUS. При необходимости, могут поддерживаться действия TRACE и REFRESH.

Поля parm1 и parm2 применяются для различных целей, в зависимости от запрошенного действия.

Действие parm1 parm2
STOP NORMAL или FORCE  
STATUS LONGSTAT или SHORTSTAT  
TRACE LONGTRACE или SHORT-TRACE TRACEON или TRACEOFF

Для действий START и REFRESH поля parm1 и parm2 не используются.

Ответ подсистемы на запрос SRC

Действия, которые выполняет система в ответ на большинство запросов SRC, задаются при определении объекта подсистемы в SRC. Структуры, применяемые подсистемами при ответе на запросы SRC, определены в файле /usr/include/spc.h. Для обработки команд в подсистемах могут применяться следующие динамические функции SRC:

Функция Описание
srcrrqs Позволяет подсистеме сохранить заголовок запроса.
srcsrpy Позволяет подсистеме отправить ответ на запрос.

Для обработки запросов на получение информации о состоянии требуется выполнить несколько задач и функций.

В ответ на неизвестный или неверный запрос подсистема должна отправить пакет с этим запросом и кодом ошибки SRC_SUBICMD. Коды действий 0-255 зарезервированы в SRC для внутреннего использования. При получении подсистемой запроса с неправильным кодом действия она должна вернуть код ошибки SRC_SUBICMD. Правильные коды действий, поддерживаемые SRC, перечислены в файле spc.h. Кроме того, вы можете определить собственные коды действий. Код действия считается неправильным, если он не определен в SRC и подсистеме.

Примечание: Коды действий 0-255 зарезервированы для SRC.

Обработка запросов SRC на получение информации о состоянии

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

Примечание: Краткие отчеты о состоянии подсистемы составляются демоном srcmstr. Код состояния и константы, описывающие состояние, которые указываются в отчетах этого типа, определены в файле /usr/include/spc.h. В таблице Константы состояния перечислены обязательные и дополнительные коды состояния, которые могут быть возвращены в ответ на запрос.

Коды состояния, которые могут встретиться в ответе

Значение Описание Подсистема Субсервер
SRCWARN Получен запрос на остановку. (Будет остановлена в течение 20 секунд.) X X
SRCACT Запущена и работает. X X
SRCINAC Не работает.    
SRCINOP Неисправна. X X
SRCLOSD Закрыта.    
SRCLSPN Закрывается.    
SRCNOSTAT Простаивает.    
SRCOBIN Открыта, но не работает.    
SRCOPND Открыта.    
SRCOPPN Открывается.    
SRCSTAR Запускается.   X
SRCSTPG Останавливается. X X
SRCTST Выполняется проверка.    
SRCTSTPN Ожидание проверки.    

Команда SRC lssrc записывает полученную информацию в стандартный вывод. Информация, которая возвращается в ответ на запрос о подробном отчете о состоянии, определяется программистом подсистемы. При необходимости подсистема может отслеживать состояние своих субсерверов и сообщать о его изменении. С помощью функции srcstathdr можно получить стандартный заголовок отчета о состоянии и добавить его к своим данным о состоянии.

Обработку запроса на получение информации о состоянии рекомендуется разбить на следующие шаги:

  1. Для возврата отчета о состоянии подсистемы (краткого или подробного), создайте массив структур statcode и структуру srchdr. Структура srchdr должна располагаться в начале буфера, отправляемого в ответ на запрос о состоянии. Структура statcode определена в файле /usr/include/spc.h. 
    struct statcode
{
   short objtype;
   short status;
   char objtext [65];
   char objname [30];
};
  2. Укажите в поле objtype константу SUBSYSTEM, если информация о состоянии относится к подсистеме, или кодовый знак субсервера, если информация относится к субсерверу.
  3. Укажите в поле status одну из констант состояния SRC, перечисленных в файле spc.h.
  4. Укажите в поле objtext текст NLS, описывающий состояние. Строка, указанная в этом поле, должна заканчиваться символом NULL.
  5. Укажите в поле objname имя подсистемы или субсервера, к которому относится значение objtext. Строка, указанная в этом поле, должна заканчиваться символом NULL.

    Примечание: Подсистема и инициатор запроса могут договориться об отправке другой информации в ответ на запрос.

Отправка пакетов с ответами подсистем

В ответ на запросы SRC подсистема должна отправлять структуру srcrep, описанную в файле /usr/include/spc.h. Ответ должен содержаться в структуре svrreply, вложенной в структуру srcrep:

struct svrreply
{
      short rtncode; /*код возврата подсистемы*/
      short objtype; /*SUBSYSTEM или  SUBSERVER*/
      char objtext[65]; /*описание объекта*/
      char objname[20]; /*имя объекта*/
      char rtnmsg[256]; /*возвращенное сообщение*/
};

Для отправки пакета с ответом предназначена функция srcsrpy.

Создание ответа

Для создания ответа подсистемы выполните следующую процедуру:

  1. Укажите в поле rtncode код ошибки SRC. Для возврата собственного сообщения NLS укажите в поле rtncode значение SRC_SUBMSG.
  2. Укажите в поле objtype константу SUBSYSTEM, если ответ отправляется от подсистемы, или кодовый знак субсервера, если ответ отправляется от субсервера.
  3. Укажите в поле objname имя подсистемы, тип субсервера или объект субсервера, от которого отправляется ответ.
  4. Укажите в поле rtnmsg свое сообщение NLS.
  5. Укажите соответствующее значение в параметре Continued команды srcsrpy. Дополнительная информация приведена в разделе "Пакеты продолжения srcsrpy".

    Примечание: При отправке последнего пакета в параметре Continued функции srcsrpy должно быть указано значение END.

Пакеты с продолжением srcsrpy

Ответ подсистемы на запрос SRC представляет собой набор пакетов с продолжением. Существует два типа пакетов с продолжением: информационное сообщение и пакет с ответом.

Информационное сообщение не возвращается клиенту. Оно записывается в стандартный вывод клиента. Сообщение должно представлять собой текст NLS с маркерами сообщения, составленный подсистемой-отправителем. Для отправки такого пакета с продолжением укажите в параметре Continued функции srcsrpy значение CONTINUED.

Примечание: В ответ на запрос действия STOP не разрешается отправлять пакеты с продолжением. В ответ на все остальные запросы SRC, полученные подсистемой, может быть отправлено информационное сообщение.

Пакет с ответом возвращается клиенту для дальнейшей обработки. Формат этого пакета должен быть согласован между инициатором и подсистемой. Примером запроса, в ответ на который может быть отправлено такое продолжение, может служить запрос на получение информации о состоянии. При получении подсистемой этого запроса укажите в параметре Continued функции srcsrpy значение STATCONTINUED. После отправки всего отчета о состоянии или всех пакетов с ответом подсистемы укажите в параметре Continued функции srcsrpy значение END. Клиенту будет передан пакет, означающий завершение ответа.

Возврат подсистемами пакетов с ошибками SRC

Подсистемы должны отправлять пакеты с информацией обо всех ошибках SRC и других ошибках.

Информация об ошибке SRC должна возвращаться подсистемой в виде структуры svrreply, вложенной в структуру srcrep. В поле objname этой структуры должно быть указано имя подсистемы, тип субсервера или объект субсервера, в котором возникла ошибка. Если сообщение NLS, связанное с данной ошибкой SRC, не содержит маркеров, возвращается пакет с краткой информацией об ошибке. Это означает, что пакет содержит только номер ошибки SRC. Если с данной ошибкой связаны маркеры, то должно быть возвращено сообщение NLS из каталога сообщений.

При возникновении ошибки, не связанной с SRC, должен быть отправлен пакет со структурой svrreply, в которой полю rtncode присвоено значение SRC_SUBMSG, а в поле rtnmsg указано сообщение NLS подсистемы. Поле rtnmsg записывается в стандартный вывод клиента.

Ответ на запросы о трассировке

Подсистема не обязана поддерживать команды traceson и tracesoff. Однако поддержка этих команд позволяет выполнять трассировку подсистемы и субсервера.

Запросы на трассировку подсистемы отправляются в виде структуры subreq, полю action которой присвоено значение TRACE, а полю object - значение SUBSYSTEM. В параметре parm1 указывается тип трассировки (LONGTRACE или SHORTTRACE), а в параметре parm2 указывается, нужно ли включить или выключить трассировку (значение TRACEON или TRACEOFF).

Если подсистема получает пакет с запросом на трассировку, в котором parm1 равен SHORTTRACE, а parm2 равен TRACEON, то подсистема должна включить функцию трассировки. Если подсистема получит пакет с запросом на трассировку, в котором parm1 равен LONGTRACE, а параметр parm2 равен TRACEON, то подсистема должна включить функцию подробной трассировки. При получении пакета с запросом, в котором parm2 будет равен TRACEOFF, подсистема должна выключить трассировку.

В запросе на трассировку субсервера поле action subreq равно TRACE, а поле object subreq содержит кодовый знак субсервера, для которого должна быть включена трассировка. В параметре parm1 указывается тип трассировки (LONGTRACE или SHORTTRACE), а в параметре parm2 указывается, нужно ли включить или выключить трассировку (значение TRACEON или TRACEOFF).

Если подсистема получает пакет с запросом на трассировку субсервера, в котором parm1 равен SHORTTRACE, а parm2 равен TRACEON, то подсистема должна включить трассировку субсервера. Если подсистема получает пакет с запросом на трассировку субсервера, в котором parm1 равен LONGTRACE, а parm2 равен TRACEON, то она должна включить подробную трассировку субсервера. При получения пакета с запросом на трассировку субсервера, в котором parm2 равен TRACEOFF, подсистема должна выключить трассировку субсервера.

Ответ на запросы об обновлении

Не все подсистемы поддерживают запросы на обновление. Подсистемы, поддерживающие команду refresh, должны отвечать на нее SRC следующим образом:

  • В запросе на обновление подсистемы поле action структуры subreq равно REFRESH, а поле object равно SUBSYSTEM. При обновлении подсистемы не применяются параметры parm1 и parm2.
  • При получении запроса на обновление подсистема должна изменить свою конфигурацию.