Приложение 3: Протокол ENMP версии 2.0¶

• Table of contents
• Приложение 3: Протокол ENMP версии 2.0
  • Общие сведения
  • Команда RESET
  • Команды GETVER и VERSION
  • Команда CALLMACRO
  • Команда GETLIST
  • Команды потоков данных
  • Команда SETCDSLIST
  • Команда SETMACRO
  • Команда SETSIGNALLIST

Общие сведения¶

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

enm [RID=RID_NUMBER]>

cmd>COMMAND_NAME

[[PARAMETER_VALUE]

…

]

/enm>

, где:

* RID_NUMBER - идентификатор запроса.

* COMMAND_NAME - имя команды или ответа. Может быть:

* RESET

* GETLIST

* GETVER

* SETCDSLIST

* SETMACRO

* SETSIGNAL

* GETSTREAM

* CALLMACRO

* CONNECTSTREAM

* DISCONNECTSTREAM

* ERROR

* VERSION

* LIST

* STREAM

• PARAMETER_NAME - имя параметра.
• PARAMETER_VALUE - значение параметра.

Команда обязательно должна заключаться внутри тэгов , первый из которых может иметь необязательный параметр RID. Если он присутствует, то все ответы на данный запрос будут иметь этот указанный идентификатор READ_NUMBER. Первым внутри команды должен идти обязательный тэг , внутри которого содержится имя команды или запроса COMMAND_NAME. Далее могут следовать один или несколько необязательных параметров. Каждый параметр должен находиться внутри тэгов . Согласно данной версии протокола каждый параметр должен быть именованым, поэтому обязательно должно быть указано его имя PARAMETER_NAME. Зато значение параметра может быть опущено в случае, когда важен только сам факт наличия параметра. Значение PARAMETER_VALUE может быть как простым, так и составным, т.е. иметь внутри себя тэговую структуру.

В общем случае выполнение команды ENM можно представить в следующем виде:

{{Image("ENMcommon.jpg","width=600px")}}

Сначала прикладная программа или другой сервер Caps-Clock формируют команду ENM и отсылают её серверу CSRV. Сервер получает команду и производит её разбор. В случае ошибки он отсылает инициатору код ошибки и прекращает выполнение команды. В случае успешного разбора он может выполнить последовательность из действий следующего типа:

• сформировать ответ на основе внутренних данных CSRV
• вызвать на выполнение одну из функций OS
• сформировать и отправить команду CCP часовой машине
• сформировать и отправить команду ENMP другому серверу Caps-Clock или прикладной программе

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

Команда RESET¶

Команда предназначена для сброса компоненты в исходное состояние.

Параметры:

Может использоваться один из двух необязательных параметров:

• ID - идентификатор компоненты в сети Caps-Clock
• IP - IP адрес компоненты

Если ни один из параметров не задан, то производится сброс той компоненты, которая эту команду принимает. Если указаны оба параметра, то используется первый корректный параметр по порядку следования.

Синтаксис:

enm [RID=xxxxx]>

cmd>RESET

[XXXXX]

[XXX.XXX.XXX.XXX]

/enm>

Выполнение:

При получении команды RESET сервер производит следующие действия:

• если команда пришла без параметров, или параметр указывает на сам сервер, то сервер закрывает все открытые соединения кроме соединения с инициатором, отправляет инициатору статус завершения операции, и в случае статуса "OK", закрывает соединение с ининциатором и выполняет сброс
• если команда пришла с параметром, то ищет в таблицах информацию о соединении с указанной компонентой и типе протокола (CCP или ENMP), затем формирует команду согласно протокола соединения и отправляет команду этой компоненте, получает ответ от неё, анализирует и отправляет инициатору статус завершения операции

{{Image("ENMreset.jpg","width=600px")}}

Ответ:

enm [RID=xxxxx]>

cmd>ERROR

prm name=ID>XXXXXX

prm name=IP>XXX.XXX.XXX.XXX

prm name=ERROR_ID>XXXXXXX

[XXXXXXXXXXX]

/enm>

В ответ сервер отсылает сообщение ERROR с ID и IP-адресом компоненты, в котором содержится статус выполнения ERROR_ID (OK или код ошибки) и необязательное описание ошибки ERROR_DESC.

Команды GETVER и VERSION¶

Команда предназначена для получения информации о том, какую версию протокола ENMP поддерживает компонента.

Параметры:

Нет.

Синтаксис:

enm [RID=xxxxx]>

cmd>GETVER

/enm>

Выполнение:

При получении команды GETVER сервер составляет ответ VERSION с указанием номера поддерживаемого протокола ENMP и отправляет его инициатору.

{{Image("ENMgetver.jpg","width=200px")}}

Ответ:

enm [RID=xxxxx]>

cmd>VERSION

prm name=MAJOR>XX

prm name=MINOR>XX

/enm>

В ответ сервер отсылает сообщение VERSION с указанием старшего MAJOR и младшего MINOR номера версии протокола ENMP (т.е. MAJOR.MINOR).

Команда CALLMACRO¶

Команда предназначена для вызова макроса на выполнение.

Параметры:

Команда имеет один обязательный параметр:

• MACRO - имя вызываемого макроса.

Остальлные параметры имеют отношение только к вызываемому макросу и опреляются его форматом. Сервер при выполнении будет передавать их макросу "как есть".

Синтаксис:

enm [RID=xxxxx]>

cmd>CALLMACRO

prm name=MACRO>XXXXXX

[XXXXX]

…

/enm>

Выполнение:

При получении команды CALLMACRO сервер производит поиск макроса в макрореестре и проверяет его на наличие/отсутствие параметров. В случае ошибки при написании команды инициатору возвращается ENM ERROR с кодом ошибки, а выполнение макрорса прекращается. Если команда составлена правильно, то макрос вызывается на выполнение. По окончании выполнения макроса возращается инициатору ENM ERROR со статусом выполнения команды (OK или код ошибки). В процессе выполнения макрос может также отсылать серверу различные сообщения, в зависимости от выполняемых им действий.

Диаграмма выполнения соответствует диграмме выполнения общей структуры команды.

Ответ:

enm [RID=xxxxx]>

cmd>ERROR

prm name=MACRO>XXXXXX

prm name=ERROR_ID>XXXXXXX

[XXXXXXXXXXX]

/enm>

В ответ сервер отсылает сообщение ERROR с указанием имени макроса MAСRО, кода ошибки ERROR_ID и необязательного описания ошибки ERROR_DESC.

Команда GETLIST¶

Команда предназначена для получения от сервера известных ему списков часовых машин, других серверов, доступных макросов и обработчиков сигналов GPI.

Параметры:

Используются два параметра:

• TYPE - тип получаемого списка (обязательный параметр)
• STATE - состояние компонентов (необязательный параметр, по умолчанию включаются все компоненты)

TYPE определяет, список каких именно компонент должен быть составлен. Он может быть:

• CLOCK_TYPE - для получения списка часовых машин.
• SERVER_TYPE - для получения списка серверов
• MACRO_TYPE – для получения списка макросов, доступных для вызова
• SIGNAL_TYPE – для получения списка сигналов GPI с обработчиками

STATE определяет состояние коспонент, которые должны быть включены в список:

• CONNECTED – подключенные в настоящее время
• DISCONNECTED – занесённые в таблицу, но неподключенные в настоящее время
• ALL – все, занесённые в таблицу

Синтаксис:

enm [RID=xxxxx]>

cmd>GETLIST

prm name=TYPE>XXXXX

[XXXXX]

/enm>

Выполнение:

При получении команды GETLIST сервер производит следующие действия: определяет вид таблицы, откуда нужно брать информацию в соответствии с TYPE, выбирает оттуда элементы, соответствующие состоянию STATE и заносит их в выходной список. После этого список кодируется в формате ENMP и отправляется инициатору.

{{Image("ENMlist.jpg","width=200px")}}

Ответ:

enm [RID=xxxxx]>

cmd>LIST

prm name=ID>XXXXXX

prm name=TYPE>XXXXXXX

[

…

/prm>]

/enm>

В ответ сервер отсылает сообщение LIST с ID компоненты и указанием типа списка TYPE и самим списком LIST, содержащим сам список.

Команды потоков данных¶

Набор команд потоков данных предназначен для установления параметров потока и подготовки к подключению.

Выполнение:

Приложение, желающее установить канал передачи потока данных с каким-либо контролом какой-либо часовой машины, посылает серверу команду ENM GETSTREAM. Если подключение к такой машине с таким контролом невозможно, то сервер отсылает инициатору ENM ERROR с описанием ошибки. Если такой контрол есть на указанной ЧМ, то сервер запрашивает по протоколу CCP возможные варианты передачи потока. Получив эту информацию, сервер формирует информационное сообщение ENM STREAM для инициатора. Инициатор выбирает нужный вариант передачи и отсылает серверу ENM CONNECTSTREAM с указанием выбранного способа передачи. Сервер информирует часовую машину о конфигурации выбранного варианта по протоколу CCP, а часовая машина в свою очередь сообщает серверу о готовности. При получении сообщения о готовности сервер отправляет инициатору ENM ERROR OK для начала передачи потока данных, или код ошибки в случае невозможности передачи. После получения этого сообщения инициатор устанавливает непосредственное соединение с указанным IP и портом и начинает передачу потоковых данных в выбранном формате. По окончании передачи он отсылает серверу ENM DISCONNECTSTREAM для сброса параметров потока. Команда GETSTREAM может использоваться также и самостоятельно для получения информации о поточных контролах.

{{Image("ENMstream.jpg","width=350px")}}

Параметры команды GETSTREAM:

В команде передаётся 2 параметра:

• CDS_ID - идентификатор часовой машины в сети Caps-Clock
• CTRL_ID - идентификатор контрола на этой машине

Синтаксис команды GETSTREAM:

enm [RID=xxxxxx]>

cmd>GETSTREAM

prm name=CDS_ID>xxxxxx

prm name=CTRL_ID>xxxxxx

/enm>

Параметры команды STREAM:

В команде STREAM передаются 2 параметра:

* CONNECTION - описывает парметры соединения TCP/IP. Этот параметр содержит 2 поля:

* IP - IP-адрес часовой машины

* PORT - номер порта, который подключен к указанному контролу потока данных

* STREAM_LIST - описывает варианты соединения. Каждый вариант соединения также состоит в свою очередь из нескольких полей:

* SID - идентификатор варианта

* LEN - длина пакета данных в байтах. 0 будет означать непрерывный поток.

* [FIELDS] - описание полей в пакете, если они есть. Необязательный параметр.

* FID - идентификатор поля

* LEN - длина поля в байтах

* [DESC] - необязательный параметр, дающий описание поля.

В дальнейшем варианты передачи данных будут адресоваться по SID. FID больше нужен часовой машине, чем инициатору.

Синтаксис команды STREAM:

_ <enm [RID=xxxxxx]>_

cmd>STREAM

prm name=CONNECTION>

IP>xxx.xxx.xxx.xxx

port>xxxx

/prm>

prm name=STREAM_LIST>

stream SID=xxxxx>

len>xxxx

[

field FID=xxxxx>

len>xxxx

[xxxxxxxxxxxx]

/field>

…

/fields>]

/stream>

…

/prm>

/enm>

Параметры команды CONNECTSTREAM:

Эта команда использует 3 параметра - 2 те же, что и команда GETSTREAM, и идентификатор варианта, присланный в ответе STREAM:

• CDS_ID - идентификатор часовой машины в сети Caps-Clock
• CTRL_ID - идентификатор контрола на этой машине
• SID - идентификатор варианта

Синтаксис команды CONNECTSTREAM:

enm [RID=xxxxxx]>

cmd>CONNECTSTREAM

prm name=CDS_ID>xxxxxx

prm name=CTRL_ID>xxxxxx

prm name=SID>xxxx

/enm>

Параметры команды DISCONNECTSTREAM:

Эта команда использует 2 параметра:

• CDS_ID - идентификатор часовой машины в сети Caps-Clock
• CTRL_ID - идентификатор контрола на этой машине

Синтаксис команды DISCONNECTSTREAM:

enm [RID=xxxxxx]>

cmd>DISCONNECTSTREAM

prm name=CDS_ID>xxxxxx

prm name=CTRL_ID>xxxxxx

/enm>

Команда SETCDSLIST¶

С помощью этой команды осуществляется управление сетевой конфигурацией часовых машин, подключенных к данному часововму серверу.

Параметры:

Два параметра определяют порядок выполнения этой команды:

• ACTION - действия, которые должны быть выполнены.
• CDS_LIST - список часовых машин в формате CLOCK_TYPE

В качестве ACTION могут использоваться следующие действия:

• ADD - для добавления списка машин к текущему
• DELETE - для удаления списка машин из текущего
• SET - текущий список целиком замещается на заданный список

Синтаксис:

enm [RID=xxxxx]>

cmd>SETCDSLIST

prm name=ACTION>XXXXXX

prm name=CDS_LIST>

…

/prm>

/enm>

Выполнение:

При получении команды SETCDSLIST сервер сопоставляет текущий список часовых машин с присланным в параметрах команды.

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

Для добавления часовой машины в список текущих сервер пытается найти эту машину в сети и установить с ней соединение. Если соединение устанавливается, то пытается получить идентификатор этой машины в сети Caps-Clock. В случае успеха статус машины в сети помечается как CONNECTED, в противном случае - DISCONNECTED.

В ответ инициатору посылается ENM ERROR со статусом выполнения операции.

{{Image("ENMcdslist.jpg","width=350px")}}

Ответ:

enm [RID=xxxxx]>

cmd>ERROR

prm name=ID>XXXXXX

prm name=IP>XXX.XXX.XXX.XXX

prm name=ERROR_ID>XXXXXXX

[XXXXXXXXXXX]

/enm>

В ответ сервер отсылает сообщение ERROR с ID и IP сервера в случае успешного завершения. При возникновении ошибки ID и IP содержат идентификатор и адрес часовой машины, над которой не удалось произвести указанное действие.

Команда SETMACRO¶

Команда предназначена для работы макрорреестром.

Параметры:

Команда использует для работы два параметра:

* ACTION - действия, которые должны быть выполнены:

* ADD - добавить макрос

* DELETE - удалить макрос

* SET - заменить макрос

• MACRO - макрос, над которым производится действие.

MACRO представляет собой сложный параметр и состоит из нескольких полей:

• NAME - имя макроса
• [BODY] – тело макроса (может быть опущено для команды DELETE)
• [DESC] - краткое текстовое описание (может отсутствовать)

Синтаксис:

enm [RID=xxxxx]>

cmd>SETMACRO

prm name=ACTION>XXXXXX

prm name=MACRO>

name>XXXXXXX

_[

_

…

/body>]

[XXXXXXXXXXXXXXX]

/prm>

/enm>

Выполнение:

При получении команды SETMACRO сервер ищет в макрореестре макрос с таким именем. Если находит, то в случае ACTION=ADD возвращается код ошибки, и выполнение команды прерывается. Для случая ACTION=DELETE макрос удаляется из макрореестра, а из таблицы событий удаляются события, связанные с этим макросом, макрореестр сохраняется, и выполнение команды заканчивается.

Далее сервер осуществляет трансляцию макроса и в случае выявления ошибки, отсылает инициатору ENM ERROR с её описанием. если трансляция прошла успешно, то для ACTION=SET из таблицы событий удаляются все события, связанные с этим макросом, а сам макрос удаляется из макрореестра.

После этого макрос заносится в макрореестр, макрореестр сохраняется, а выполнение команды заканчивается.

В ответ инициатору посылается ENM ERROR со статусом выполнения операции.

{{Image("ENMsetmacro.jpg","width=260px")}}

Ответ:

enm [RID=xxxxx]>

cmd>ERROR

prm name=ID>XXXXXX

prm name=IP>XXX.XXX.XXX.XXX

prm name=ERROR_ID>XXXXXXX

[XXXXXXXXXXX]

/enm>

В ответ сервер отсылает сообщение ERROR с ID и IP сервера и с кодом ошибки и её описанием. При ошибке трансляции описание ошибки содержит номер строки и сбойный тэг, в котором обнаружена ошибка.

Команда SETSIGNALLIST¶

Команда предназначена для работы с таблицей сигналов.

Параметры:

Команда использует для работы два параметра:

* ACTION - действия, которые должны быть выполнены:

* ADD - добавить обработчик

* DELETE - удалить обработчик

* SET - заменить обработчик

• SIGNAL - обработчик сигнала, над которым производится действие.

SIGNAL представляет собой сложный параметр и состоит из нескольких полей:

* ID - идентификатор сигнала

* TYPE – тип сигнала. Может быть:

* HWSIGNAL - сигнал от устройства GPI

* ENMPNOTIFY - уведомление по протоколу ENMP

* CCPNOTIFY - уведомление по протоколу CCP

* ENMPERROR - сообщение о статусе выполнения по протоколу ENMP

* CCPERROR - сообщение о статусе выполнения по протоколу CCP

* ?TIMER - сигнал от таймера

* [CHECK] - параметр, показывающий, нужна ли проверка данных на совпадение. Если проверка не требуется, то параметр может быть опущен. Состоит из полей описания данных в формате CML.

* [MACRO] - описание вызова макроса. Может отсутствовать для команды DELETE. Состоит также из нескольких полей:

* NAME - имя макроса

* [PRM NAME=XXXXXX] - возможен список именованных параметров со значениями.

• [DESC] - краткое текстовое описание (может отсутствовать)

Синтаксис:

enm [RID=xxxxx]>

cmd>SETSIGNAL

prm name=ACTION>XXXXXX

prm name=SIGNAL>

id>XXXXXXX

type>XXXXXX

[

…

/check>]

macro name=XXXXXX>

[XXXXX]

…

/macro>

[XXXXXXXXXXXXXXX]

/prm>

/enm>

Выполнение:

При получении команды SETSIGNAL сервер ищет в таблице событий обработчик с таким идентификатором. Если находит, то в случае ACTION=ADD возвращается код ошибки, и выполнение команды прерывается. Для случая ACTION=DELETE обработчик удаляется из таблицы событий, таблица сохраняется, и выполнение команды заканчивается.

Далее сервер осуществляет трансляцию обработчика и в случае выявления ошибки, отсылает инициатору ENM ERROR с её описанием. если трансляция прошла успешно, то для ACTION=SET обработчик удаляется из таблицы событий.

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

В ответ инициатору посылается ENM ERROR со статусом выполнения операции.

{{Image("ENMsetsignal.jpg","width=260px")}}

Ответ:

enm [RID=xxxxx]>

cmd>ERROR

prm name=ID>XXXXXX

prm name=IP>XXX.XXX.XXX.XXX

prm name=ERROR_ID>XXXXXXX

[XXXXXXXXXXX]

/enm>

В ответ сервер отсылает сообщение ERROR с ID и IP сервера и с кодом ошибки и её описанием. При ошибке трансляции описание ошибки содержит номер строки и сбойный тэг, в котором обнаружена ошибка.