Создание соединения с помощью конфигурации соединения – LINTER_ConnectEnvEx/ LINTER_ConnectEnv
Прототипы функций
L_LONG LINTER_ConnectEnvEx( L_CHAR *sCfgName, /* имя конфигурации соединения */ L_SWORD swCfgNameLen, /* длина имени конфигурации соединения */ L_LONG *plMode, /* режим работы создаваемого соединения */ L_WORD pwConnectionId, /* идентификатор созданного соединения */ L_LONG *plApiError, /* код завершения LinAPI */ L_LONG *plLinError, /* код завершения СУБД ЛИНТЕР */ L_LONG *plSysError); /* код завершения ОС */
Устаревший вариант:
L_LONG LINTER_ConnectEnv( L_CHAR *sCfgName, /* имя конфигурации соединения */ L_SWORD swCfgNameLen, /* длина имени конфигурации соединения */ L_LONG *plMode, /* режим работы создаваемого соединения */ L_WORD pwConnectionId);/* идентификатор созданного соединения */
Входные параметры
| Параметр | Описание | |
|---|---|---|
sCfgName
| Имя конфигурации соединения. Если аргумент не задан, по умолчанию используется имя LINTER | |
swCfgNameLen
| Длина имени конфигурации соединения (максимально допустимая длина 58 символов). Если строка sCfgName ограничена символом '\0', то можно указать нулевое значение длины | |
plMode
| Режим работы создаваемого соединения | |
pwConnectionId
| Идентификатор соединения |
Режимы работы создаваемого соединения (определены в заголовочном файле linapi.h):
-
mAutocommit – режим транзакций AUTOCOMMIT;
-
mOptimistic – режим транзакций OPTIMISTIC;
Примечание
Режим OPTIMISTIC устарел (использовать не рекомендуется).
Выходные параметры
| Параметр | Описание | |
|---|---|---|
pwConnectionId
| Идентификатор созданного соединения | |
plMode
| Установленный режим соединения | |
plApiError
| Код завершения LinAPI-интерфейса | |
plLinError
| Код завершения СУБД ЛИНТЕР | |
plSysError
| Код завершения ОС |
Описание
Функция предназначена для создания соединения с ЛИНТЕР-сервером на основе определяемой клиентским приложением конфигурации соединения.
Клиентское приложение может содержать любое количество конфигураций соединения и использовать их в соответствии со своей логикой работы (например, в случае отказа в доступе к локальному ЛИНТЕР-серверу попытаться установить соединение с удаленным ЛИНТЕР-сервером).
Для идентификации используемой при создании соединения конфигурации соединения используется имя конфигурации, которое задается в аргументе sCfgName данной функции.
Для каждой конфигурации соединения в ОС должны быть созданы две переменных окружения, определяющие следующие значения:
-
вид создаваемого соединения (локальное или сетевое);
-
спецификацию файла с параметрами создаваемого соединения
Формат переменной окружения, задающей вид создаваемого соединения:
CONNECT< подчёркивание >< имя конфигурации соединения >=< значение переменной CONNECT >
< имя конфигурации соединения >::= < значение параметра sCfgName >
< значение переменной CONNECT >::= < локальное соединение > | < сетевое соединение >
< локальное соединение >::=1:< значение LINTER_MBX >
< сетевое соединение >::=2:< имя ЛИНТЕР-сервера >
Примечание
Если переменная окружения CONNECT_" + sCfgName задает локальное соединение, то функция должна использоваться только в том случае, если у клиентского приложения нет других локальных соединений.
< значение LINTER_MBX >:= идентификатор межзадачного обмена (см. документ «СУБД ЛИНТЕР. Сетевые средства», раздел «Управление сетевым доступом»)
< имя ЛИНТЕР-сервера >::= имя узла локальной сети из файла сетевой конфигурации nodetab (см. документ «СУБД ЛИНТЕР. Сетевые средства», раздел «Файл сетевой конфигурации»)
Примеры
CONNECT_DEMO=1:30000 CONNECT_NETDEMO=2:NODE1
Формат переменной окружения, задающей параметры создаваемого соединения:
CFG< подчёркивание >< имя конфигурации соединения >=< значение переменной CFG >
< значение переменной CFG >::=< спецификация файла >
< спецификация файла >::= путь и имя текстового файла с параметрами соединения
Формат текстового файла с параметрами соединения. Текстовый файл состоит из строк следующего формата:
< строка >::= < имя параметра >=< значение параметра >
< имя параметра >::= USER | PASSWORD | CODEPAGE | CONCURRENCY
Имена параметров регистронезависимы.
< значение параметра >:
-
USER – имя пользователя БД (строка длиной до 66 символов)
-
PASSWORD – пароль пользователя БД (строка длиной до 18 символов)
-
CODEPAGE – имя кодировки соединения (символьная строка)
-
CONCURRENCY – режим транзакций соединения (одно или несколько значений (с учётом регистра!)):
-
mAutocommit;
-
mOptimistic;
Примечание
Режим mOptimistic устарел (использовать не рекомендуется).
-
mExclusive.
-
Если значения в файле не заданы, то для параметров USER, PASSWORD, CODEPAGE будет устанавливаться пустая строка, а для параметра CONCURRENCY – значение 0 (соответствует mAutocommit).
Если один и тот же параметр задан несколько раз, используется последнее значение параметра.
Разделитель между значениями может быть произвольным строковым символом – пробелом, запятой и т.д.
Примеры
Переменные среды окружения (предполагается, что БД запущена локально с LINTER_MBX=20561): CONNECT_LINTER=1:20561 CFG_LINTER=config.lin Файл config.lin: USER=SYSTEM PASSWORD=MANAGER8 CODEPAGE=CP1251 CONCURRENCY=mExclusive
После обработки конфигурации соединения происходит вызов функции LINTER_ConnectCSEx с извлеченными параметрами из конфигурации соединения.
Функция LINTER_ConnectEnvEx возвращает коды завершения в выходных параметрах, а для получения кодов завершения функции LINTER_ConnectEnv необходимо после её выполнения вызывать дополнительно функцию LINTER_GetError.
Пример
1) Создание и настройка конфигурации локального соединения с именем LOCAL_DB (с LINTER_MBX=3000):
-
создание файла параметров соединения param_local.lin:
USER=USER1 PASSWORD=12345 CODEPAGE=CP1251 CONCURRENCY=mAutocommit
-
создание и установка переменных окружения:
SET CONNECT_LOCAL_DB = 1:3000 SET CFG_LOCAL_DB=param_local.lin (файл будет взят из каталога запуска клиентского приложения)
2) Создание и настройка конфигурации удаленного соединения с именем REMOTE_DB (имя сервера NODE1):
-
создание файла параметров соединения param_remote.lin:
USER=USER1 PASSWORD=12345 CODEPAGE=CP1251 CONCURRENCY=mAutocommit
-
создание и установка переменных окружения:
SET CONNECT_REMOTE_DB =2:NODE1 SET CFG_REMOTE_DB=c:\linter\param_remote.lin
3) Вызов функции
long lError, lTransactionMode;
short nConnID;
...
If (lError =LINTER_ConnectEnv("LOCAL_DB", 0, &lTransactionMode, &nConnID))
Processing_error(lError, nConnID, 0, 0, "LINTER_local_Connect");
...
If (lError =LINTER_ConnectEnv("REMOTE_DB", 0, &lTransactionMode, &nConnID))
Processing_error(lError, nConnID, 0, 0, "LINTER_remote_Connect");