Описанные в этом разделе функции позволяют работать непосредственно с протоколом MMP, т.е. отправлять команды и читать ответы сервера.
mmpSendCmd(handle,command)
Функция отправляет на сервер команду
command
. При успешном выполнении функция
возвращает строку SUCCESS:
после чего
ответ может быть прочитан одним или несколькими вызовами функции mmpRead. В случае ошибки функция
возвращает строку ERROR:
.code
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 хранящуюся в виде отдельных частей которые собираются перед отправкой на сервер. Отдельные части подготовленного объекта могут изменяться перед повторной отправкой команды.
Жизненный цикл подготовленного объекта обычно выглядит так:
Создание объекта функцией mmpStmtCreate.
Привязка значений к параметрам объекта с помощью mmpStmtBind.
Отправка команды из подготовленного объекта на сервер с помощью функции mmpSendStmt и чтение ответов вызовами mmpRead.
Если необходимо отправить команду с новыми значениями - перейти к пункту 2.
Уничтожение подготовленного объекта с помощью mmpStmtDestroy.
mmpStmtCreate(string)
Создаёт объект на основе шаблона заданного аргументом
string
. Шаблон представляет из себя
строку у которой позиции привязок значений обозначены символами "?".
Позже, к этим позициям будет необходимо привязать значения с помощью
mmpStmtBind.
Пример строки для создания подготовленного объекта:
CREATE USER ? PASSWORD ? LIMIT 1gb DEPTHMAX ?
При создании подготовленного объекта к позиции может быть привязано имя файла которое указывается после символа "@". При отправке команды в соответствующем месте будет передано содержимое файла в виде лексемы:
VCARD u1 ?@user_info.vcf
При успешном выполнении функция вернёт описатель
подготовленного объекта - положительное целое число больше нуля.
Созданный объект после использования необходимо уничтожить с помощью
mmpStmtDestroy. В случае
ошибки (нехватки памяти) функция возвращает строку
ERROR:ERROR
.
mmpStmtDestroy(handle)
Функция уничтожает подготовленный объект. Аргумент
handle
- описатель полученный функцией
mmpStmtCreate.
mmpStmtBind(handle,position,value[,type])
Функция привязывает значение value
к подготовленному объекту handle
в
позиции position
. Позиции заданные при
создании подготовленного объекта считаются от нуля. Если привязка к
позиции position
уже выполнена, она будет
заменена новым значением. Необязательный аргумент
type
явно указывает формат в котором
должно быть представлено значение
value
:
Привязывает значение "как есть", точная копия строки
value
.
Строка в кавычках, перед кавычками и знаками "\"
являющимися частью строки value
будут добавлены экранирующие знаки "\".
Значение value
будут передано
в виде лексемы.
Содержимое локального файла, имя которого задано
аргументом value
, будет передано в
виде лексемы.
Если аргумент type
опущен,
представление значения будет выбрано автоматически: LEXEME - если
value
содержит переводы строк, STRING -
если value
содержит пробелы, табуляции,
символы двойных кавычек, но не переводы строк, PLAIN - в остальных
случаях.
При успешном выполнении функция возвращает строку
SUCCESS:
. В случае ошибки
возвращается одно из следующих значений:
ERROR:INVALIDARGUMENT
Указанная позиция position
не
существует в подготовленном объекте.
ERROR:ERROR
Общая ошибка (недостаточно памяти).
mmpSendStmt(handle,stmt_handle)
Функция отправляет на сервер команду которая является
результатом сборки подготовленного объекта
stmt_handle
со всеми привязками. Аргумент
handle
является описателем сессии
созданной mmpCreate.
При успешном выполнении функция возвращает строку
SUCCESS:
после чего ответ может
быть прочитан одним или несколькими вызовами функции mmpRead. В случае ошибки функция
возвращает строку ERROR:
.code