Программный доступ к клиентской библиотеке

Клиентская библиотека Инфо-Сервера 2.0 может быть использована для создания утилит и расширений Инфо-Бухгалтера сторонними разработчиками. Для этого библиотека infs2cln.dll предоставляет программный интерфейс (API), который, в частности, использует сетевая версия программы Инфо-Бухгалтер. Использование клиентской библиотеки Инфо-Сервера 2.0 предоставляет все преимущества работы в логически согласованном пространстве базы данных. Использование автоинкрементальных значений и блокировок записей позволяет безопасно функционировать утилите одновременно с работой пользователей Инфо-Бухгалтера. По такой схеме могут работать различные конвертеры, добавляющие/изменяющие записи в базе данных Инфо-Бухгалтера.

Ниже приведено описание API функций библиотеки infs2cln.dll, сигнатуры функций представлены для C и Delphi.

Инициализация библиотеки.

C/C++: extern "C" bool STDCALL is2_Init(const char* phost_addr, long port);
Delphi: function is2_Init(phost_addr: pchar; port: longint): boolean; stdcall;

phost_addr - [вход] ip-адрес или сетевое имя сервера. Например, "localhost" или "223.103.0.1".
port - [вход] порт сервера (обычно, 85).

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

В случае успешного вызова функция возвращает true, в случае ошибки - false и дополнительная информация может быть получена функцией is2_LastError. После успешного вызова is2_Init и завершения работы с Инфо-Сервером должна быть вызвана функция is2_Done.

В случае создания dll для использования из Инфо-Бухгалтера, нет необходимости вызывать эту функцию, т.к. она уже вызвана Инфо-Бухгалтером с параметрами, заданными в ibw.ini.

Деинициализация библиотеки.

C/C++: extern "C" bool STDCALL is2_Done();
Delphi: function is2_Done: boolean; stdcall;

Функция деинициализации вызывается при завершении работы с Инфо-Сервером.

В случае успешного вызова функция возвращает true, в случае ошибки - false и дополнительная информация может быть получена функцией is2_LastError. Функция is2_Done должна быть вызвана после успешного вызова is2_Init.

В случае создания dll для использования из Инфо-Бухгалтера, нет необходимости вызывать эту функцию, т.к. она будет вызвана при выходе из Инфо-Бухгалтера.

Получение текста последней ошибки.

C/C++: extern "C" bool STDCALL is2_LastError(char* pbuf, long buf_len);
Delphi: function is2_LastError(pbuf: pchar; buf_len: longint): boolean; stdcall;

pbuf - [выход] буфер для получения текста размером как минимум buf_len + 1.
buf_len - [вход] максимальное количество символов сообщения.

Функция может быть вызвана после возврата false любой другой функцией API для получения текстового сообщения об ошибке. В случае успешной передачи текста функция возвращает true, в случае отстутвия последней ошибки false.

Выполнение SQL-запроса.

C/C++: extern "C" bool STDCALL is2_ExecSQL(const char* pdb_dir, const char* puser_name, const char* pquery);
Delphi: function is2_ExecSQL(pdb_dir, puser_name, pquery: pchar): boolean; stdcall;

pdb_dir - [вход] директория базы данных.
puser_name - [вход] имя пользователя.
pquery - [вход] SQL-запрос (INSERT, UPDATE, DELETE).

Функция удаленно выполняет SQL-запрос, модифицирующий базу данных.

В случае успешного вызова функция возвращает true, в случае ошибки - false и дополнительная информация может быть получена функцией is2_LastError.

Получение автоинкрементального значения.

C/C++: extern "C" bool STDCALL is2_GetAutoInc(const char* pdb_dir, const char* puser_name, const char* pcounter_name, bool* pneed_calc, long* pid);
Delphi: function is2_GetAutoInc(pdb_dir, puser_name, pcounter_name: pchar; var need_calc: boolean; var id: longint): boolean; stdcall;

pdb_dir - [вход] директория базы данных.
puser_name - [вход] имя пользователя.
pcounter_name - [вход] имя счетчика (параметр введен в версии 2.01).
pneed_calc - [выход] true - нужен расчет автоинкрементального значения, false - расчет не нужен.
pid - [выход] очередное значение автоинкрементального счетчика.

Функция получает очередное значение заданного автоинкрементального счетчика для заданной базы данных. Если расчет по таблицам еще не был выполнен, то возвращается соответствующий признак (need_calc), а значение (id) не изменяется. Полученное значение может быть подставлено в операторы INSERT для добавления новых записей.

ВНИМАНИЕ! При использовании в Инфо-Бухгалтере расчет значения автоинкрементального счетчика с именем "IB" происходит по известным таблицам базы, поэтому применение этого счетчика для других таблиц может привести к ошибкам. Когда Инфо-Сервер 2.0 используется для модификации отдельной базы (не hozop.db, provod.db и т.д.), то в списке таблиц/полей функции is2_CalcAutoInc необходимо указывать все таблицы, куда планируется делать INSERT.

Расчет автоинкрементального значения.

C/C++: extern "C" bool STDCALL is2_CalcAutoInc(const char* pdb_dir, const char* puser_name, const char* pcounter_name, const char* ptf_list, long* pid);
Delphi: function is2_CalcAutoInc(pdb_dir, puser_name, pcounter_name, ptf_list: pchar; var id: longint): boolean; stdcall;

pdb_dir - [вход] директория базы данных.
puser_name - [вход] имя пользователя.
pcounter_name - [вход] имя счетчика (параметр введен в версии 2.01).
ptf_list - [вход] список пар таблица - ключевое поле, по которым следует вычислить максимальное значение. Формат списка: "<таблица1>:<поле1>, <таблица2>:<поле2>,...,<таблицаN>:<полеN>".
pid - [выход] очередное значение автоинкрементального счетчика.

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

ВНИМАНИЕ! При использовании в Инфо-Бухгалтере расчет значения автоинкрементального счетчика "IB" происходит по известным таблицам базы. Список таблиц/полей, передаваемый Инфо-Бухгалтером, выглядит следующим образом: "HOZOP:OPER_NUMB,PROVOD:PROVID,PLSCET:SCETID,OPREDEL:RMID,REKVISIT:RMID,PLOST:OSID". Поэтому расчет автоинкрементального счетчика "IB" для другого набора таблиц, приведет к установке неправильного значения этого счетчика. Для обслуживания дополнительных таблиц используйте счетчики с другими именами. В разных базах данных счетчики с одинаковыми именами независимы. Для самостоятельного добавления записей в таблицы базы Инфо-Бухгалтера надо пользоваться счетчиком с именем "IB".

Сохранение результатов запроса.

C/C++: extern "C" bool STDCALL is2_SaveResult(const char* pdb_dir, const char* puser_name, const char* pquery, const char* ptable_name, const char* ptable_type);
Delphi: function is2_SaveResult(pdb_dir, puser_name, pquery, ptable_name, ptable_type: pchar): boolean; stdcall;

pdb_dir - [вход] директория базы данных.
puser_name - [вход] имя пользователя.
pquery - [вход] SQL-запрос (SELECT, определяющий выборку для сохранения, или INSERT, UPDATE, DELETE).
ptable_name - [вход] имя таблицы для сохранения результата запроса (может быть 0/nil).
ptable_type - [вход] тип таблицы для сохранения результата запроса: "PARADOX" или "DBASE" (может быть 0/nil).

Функция сохраняет результат выборки запроса SELECT в таблицу базы данных. Существующая таблица перезаписывается. Могут задаваться и запросы INSERT, UPDATE и DELETE с пустым именем таблицы. В этом случае поведение аналогично функции is2_ExecSQL.

Управление блокировками.

C/C++: extern "C" bool STDCALL is2_Lock(const char* pdb_dir, const char* puser_name, long mode, const char* ptable_name, long id, bool* plock_res, char* plock_info, long buf_len);
Delphi: function is2_Lock(pdb_dir, puser_name: pchar; mode: longint; ptable_name: pchar; id: longint; var lock_res: boolean; plock_info: pchar; buf_len: longint): boolean; stdcall;

pdb_dir - [вход] директория базы данных.
puser_name - [вход] имя пользователя.
mode - [вход] режим блокировки: 0 - установка блокировки, 1 - снятие блокировки, -1 - снятие всех блокировок.
ptable_name - [вход] имя таблицы.
id - [вход] идентификатор записи в заданной таблице.
plock_res - [выход] результат блокировки: true - успешно, false - отказ.
plock_info - [выход] буфер для занесения имени заблокировавшего запись пользователя (только для mode = 0, иначе может быть 0/nil), буфер должен иметь размер как минимум buf_len + 1.
buf_len - [вход] максимальное количество символов в буфере для занесения имени заблокировавшего запись пользователя (только для mode = 0, иначе может быть 0).

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

Основная страница.