Отправка команд и получение ответов.
Пред. | Глава 8. Интерфейс для OS/2 REXX. | След.

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

Описанные в этом разделе функции позволяют работать непосредственно с протоколом 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``.

Пред. | Наверх | След.
Начало и завершение сеанса. | Начало | Высокоуровневые функции.