Отправка команд и получение ответов.

Описанные в этом разделе функции позволяют работать непосредственно с протоколом MMP, т.е. отправлять команды и читать ответы сервера.

Функция mmpSendCmd.

mmpSendCmd(handle,command)

Функция отправляет на сервер команду command. При успешном выполнении функция возвращает строку SUCCESS: после чего ответ может быть прочитан одним или несколькими вызовами функции mmpRead. В случае ошибки функция возвращает строку ERROR:code.

Функция mmpRead.

mmpRead(handle,stem)

Функция читает один ответ сервера после успешной отправки команды вызовом mmpSendCmd или mmpSendStmt. Сервер может отправить несколько *-ответов и завершающий ответ OK, NO или BYE, поэтому может понадобиться несколько вызовов mmpRead для получения всех данных которые отправил сервер в ответ на команду. Однако, не обязательно получать все переданные сервером данные перед отправкой следующей команды, в этом случае, не полученные сценарием ответы будут получены и отброшены перед отправкой следующей команды.

При успешном выполнении функция возвращает строку SUCCESS:. и заполняет переменную-основу (stem) REXX. Имя переменной задаётся вторым аргументом. После возврата переменная будет содержать:

stem.0

количество (n) записей в stem (результат + аргументы),

stem.1

результат выполнения: OK, NO или BYE,

stem.2

первый аргумент,

stem.3

второй аргумент,

stem.n

последний аргумент.

В случае ошибки функция возвращает строку ERROR:code.

Подготовленный объект команды.

Подготовленный объект представляет собой отдельную команду протокола MMP хранящуюся в виде отдельных частей которые собираются перед отправкой на сервер. Отдельные части подготовленного объекта могут изменяться перед повторной отправкой команды.

Жизненный цикл подготовленного объекта обычно выглядит так:

  1. Создание объекта функцией mmpStmtCreate.

  2. Привязка значений к параметрам объекта с помощью mmpStmtBind.

  3. Отправка команды из подготовленного объекта на сервер с помощью функции mmpSendStmt и чтение ответов вызовами mmpRead.

  4. Если необходимо отправить команду с новыми значениями - перейти к пункту 2.

  5. Уничтожение подготовленного объекта с помощью mmpStmtDestroy.

Функция mmpStmtCreate.

mmpStmtCreate(string)

Создаёт объект на основе шаблона заданного аргументом string. Шаблон представляет из себя строку у которой позиции привязок значений обозначены символами "?". Позже, к этим позициям будет необходимо привязать значения с помощью mmpStmtBind.

Пример строки для создания подготовленного объекта:

CREATE USER ? PASSWORD ? LIMIT 1gb DEPTHMAX ?

При создании подготовленного объекта к позиции может быть привязано имя файла которое указывается после символа "@". При отправке команды в соответствующем месте будет передано содержимое файла в виде лексемы:

VCARD u1 ?@user_info.vcf

При успешном выполнении функция вернёт описатель подготовленного объекта - положительное целое число больше нуля. Созданный объект после использования необходимо уничтожить с помощью mmpStmtDestroy. В случае ошибки (нехватки памяти) функция возвращает строку ERROR:ERROR.

Функция mmpStmtDestroy.

mmpStmtDestroy(handle)

Функция уничтожает подготовленный объект. Аргумент handle - описатель полученный функцией mmpStmtCreate.

Функция mmpStmtBind.

mmpStmtBind(handle,position,value[,type])

Функция привязывает значение value к подготовленному объекту handle в позиции position. Позиции заданные при создании подготовленного объекта считаются от нуля. Если привязка к позиции position уже выполнена, она будет заменена новым значением. Необязательный аргумент type явно указывает формат в котором должно быть представлено значение value:

PLAIN

Привязывает значение "как есть", точная копия строки value.

STRING

Строка в кавычках, перед кавычками и знаками "\" являющимися частью строки value будут добавлены экранирующие знаки "\".

LEXEME

Значение value будут передано в виде лексемы.

FILE

Содержимое локального файла, имя которого задано аргументом value, будет передано в виде лексемы.

Если аргумент type опущен, представление значения будет выбрано автоматически: LEXEME - если value содержит переводы строк, STRING - если value содержит пробелы, табуляции, символы двойных кавычек, но не переводы строк, PLAIN - в остальных случаях.

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

ERROR:INVALIDARGUMENT

Указанная позиция position не существует в подготовленном объекте.

ERROR:ERROR

Общая ошибка (недостаточно памяти).

Функция mmpSendStmt.

mmpSendStmt(handle,stmt_handle)

Функция отправляет на сервер команду которая является результатом сборки подготовленного объекта stmt_handle со всеми привязками. Аргумент handle является описателем сессии созданной mmpCreate.

При успешном выполнении функция возвращает строку SUCCESS: после чего ответ может быть прочитан одним или несколькими вызовами функции mmpRead. В случае ошибки функция возвращает строку ERROR:code.