определить курсор, в котором имена полей соответствуют именам (и типам) полей загружаемой таблицы. Если имя поля таблицы содержит нестандартные символы, совпадает с ключевым словом и т.д. (т.е. требует квотации), в описании поля курсора можно явно указать имя, какое должно использоваться. Для этого после типа столбца можно указать ключевое слово column и строку в кавычках, например:

cursor(
  i int; // будет соответствовать столбцу "I"
  l char(20) column "lowercase" // будет соответствовать столбцу "lowercase"
  ins date column "INSERT" // будет соответствовать столбцу "INSERT"
);

перед добавлением выдать оператор:

start append into < таблица > from < курсор >;

где:

< таблица > – имя таблицы;

< курсор > – курсорная переменная.

Выполнение этого оператора внутри процедуры приводит к подаче SQL-запроса start append into byte (< список столбцов > согласно именам полей в таблице).

В случае ошибки при выполнении оператора формируется исключение с кодом завершения.

В случае если < курсор > – недопустимое выражение, вызывается исключение BADPARAM.

При попытке выполнить start append или execute, когда предыдущий start append не был завершен при помощи end append, возникает исключение APPENDACTIVE.

чтобы добавить строку, надо заполнить поля соответствующими значениями и выдать оператор:

putm < буфер >;

В качестве < буфера > можно использовать любую переменную типа курсор, структура которой совпадает со структурой переменной, использованной в операторе start append. В случае несовпадения возникнет исключение BADCURSOR.

Этот оператор накапливает данные во внутренней странице пакета (которая выделяется оператором start append) и, если пакет заполняется, загружает его в таблицу.

Если в процессе формирования пакета и загрузки его в таблицу возникает ошибка, то вырабатывается исключение с кодом завершения, который можно получить с помощью функции errcode().

Если возникает ошибка, внутренняя страница продолжает содержать данные, которые не удалось добавить, а новая запись игнорируется.

Чтобы очистить внутреннюю страницу, можно использовать функцию

clearPutm()

Узнать количество записей во внутренней странице (которые еще не занесены реально в БД) можно при помощи функции

int getPutmRecs()

Эту функцию можно использовать, в частности, после возникновения ошибки в putm. Ошибка означает, что не все записи из внутренней страницы добавлены. Функция

getPutmRecs()

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

Можно потребовать принудительно сбросить записи из внутренней страницы в БД при помощи функции

flushPutm()

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

В случае ошибки обработка внутренней страницы аналогична выполнению оператора putm, попытавшегося сбросить заполненную внутреннюю страницу и столкнувшегося с ошибкой: внутренняя страница не очищается. Очистить ее всегда можно при помощи clearPutm().

Таким образом, вызов подряд putm и flushPutm() приведет, фактически, к добавлению строк по одной через механизм пакетного добавления.

Если перед подачей putm вызовом функций getPutmRecs, clearPutm и flushPutm не был выполнен оператор start append, или он завершился неудачно, то при попытке выполнить putm возникнет исключение APPENDNOTSTARTED.

по окончании добавления надо выдать оператор end append.

Если перед подачей end append не было вызвано оператора start append, или он завершился неудачно, то при попытке выполнить end append возникнет исключение APPENDNOTSTARTED.

После каждого start append должен вызываться end append, прежде чем делать другие execute или start append!

все операции putm выполняются по одному курсору, по тому же, что и execute в процедурах ("курсору по умолчанию").

Соответственно, между start append и end append нельзя использовать другие start append или execute. Если пытаться сделать это, возникнет исключение QUERYWHENAPPEND (если его не обработать, последующая попытка выполнения SQL-оператора приведет к получению кода завершения 1013 – неверная последовательность команд).