Доступные версии документации

Открыть канал (соединение)

Назначение
 

Команда OPEN используется для установления логической связи между клиентским приложением и СУБД ЛИНТЕР.

Параметры вызова

inter(CBL, VarBuf, [OpBuf], [CondBuf], [RowBuf]);

Входные данные

Входными данными являются:

  • контрольный блок CBL;

  • буфер параметров команды VarBuf;

  • буфер SQL-запросов OpBuf;

  • буфер для получения параметров БД RowBuf

В контрольном блоке должны быть заполнены поля:

Имя поля Значение
Prior Приоритет канала
Command "OPEN"
Node Имя ЛИНТЕР-сервера
PrzExe Режим обработки запросов
LnBufRow Длина буфера RowBuf (если RowBuf задан)

Примечание

Если поле Node содержит пробелы, то предполагается, что устанавливается соединение c СУБД на локальной машине или с сервером по умолчанию. Поле Node имеет существенное значение, ибо номера открытых на разных серверах каналов могут совпадать. Это правило справедливо для всех команд интерфейса нижнего уровня.

Буфер параметров команды VarBuf должен содержать имя и пароль зарегистрированного в БД пользователя, под чьим именем клиентское приложение будет взаимодействовать с БД.

Буфер SQL-запросов OpBuf может содержать имя устанавливаемой для данного канала кодовой страницы, которая должна быть известна СУБД. Список доступных кодовых страниц находится в системной таблице LINTER_SYSTEM_USER.$$$CHARSET.

При этом:

  1. при указании способа CP_AS_NUM (значение 0) соответствие кодовой страницы ищется в столбце WIN_CODE таблицы LINTER_SYSTEM_USER.$$$CHARSET;

  2. при указании способа CP_AS_STR (значение 1) кодовая страница ищется среди

    • предопределенных кодовых страниц ("UTF-8","UCS2");

    • кодовых страниц в системной таблице LINTER_SYSTEM_USER.$$$CHARSET (столбец NAME);

    • синонимов кодовых страниц в системной таблице LINTER_SYSTEM_USER.$$$CSALIAS.

  3. в случае если кодовая страница не найдена ни среди предопределенных значений, ни в таблицах LINTER_SYSTEM_USER.$$$CHARSET, LINTER_SYSTEM_USER.$$$CSALIAS, то ядром СУБД используется кодовая страница с именем DEFAULT (или встроенная ASCII 7 кодировка, если нет DEFAULT);

  4. при ошибке в имени кодировки ядро СУБД ЛИНТЕР использует входные данные в кодировке с именем DEFAULT из таблицы $$$CHARSET (о чём сообщает флагами в структуре OPEN_DESC возвращаемой при открытии соединения).

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

Заданная в команде OPEN кодовая страница имеет более высокий приоритет по сравнению с переменной окружения LINTER_CP.

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

  • имя и пароль, разделенные символом «косая черта» (/), нужно указывать одной строкой;

  • в имени/пароле могут быть использованы только алфавитно-цифровые символы;

  • имя/пароль могут быть взяты в кавычки ("). В этом случае символы имени/пароля используются в том виде, в каком они представлены (в нижнем/верхнем регистре, в русской/латинской транскрипции);

  • если кавычки отсутствуют, то все буквы имени/пароля будут приведены к верхнему регистру;

  • если имя/пароль содержат кавычки, то все кавычки должны быть удвоены;

  • символьная строка в VarBuf должна заканчиваться двоичным нулем.

Пример.

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

Имя пользователя Пароль
SYSTEM MANAGER
Sys" abD

Ниже приведено несколько иллюстраций употребления имени и пароля при обращении к СУБД:

Пример ввода имени и пароля Восприятие СУБД ЛИНТЕР Комментарий
System/Manager SYSTEM+MANAGER Правильно
"system"/"manager" system+manager Ошибка доступа, т.к. нет перевода к верхнему регистру
"SYSTEM/MANAGER" SYSTEM/MANAGER Ошибка доступа, т.к. будет трактоваться как одно слово
"Sys"""/"abD" Sys"+abD Правильно
"Sys""/abD Sys"/abD… Ошибка доступа, т.к. будет трактоваться как одно слово без закрывающей кавычки
Sys"/abD SYS"+ABD Будет зафиксирована ошибка доступа, т.к. не закрыта кавычка

Примечание

Если не указано имя и/или пароль, то по умолчанию имя равно MAX_ID_LEN пробелам, пароль – 18 пробелам.

Выходные данные

Выходными данными является контрольный блок CBL и буфер RowBuf (если задан).

В контрольном блоке будут возвращены:

Имя поля Значение
CodErr Код завершения запроса к СУБД ЛИНТЕР
NumChan Номер канала
SysErr Код состояния ОС

Если задан аргумент RowBuf, то в буфере возвращается структура данных OPEN_DESC, содержащая описание параметров БД, с которой установлено соединение:

typedef struct {
    L_LONG VerMajor;
    L_LONG VerMinor;
    L_LONG VerBuild;
    L_BYTE Flags;
    L_BYTE Reserv;
    L_WORD MaxRecSize;
    L_CHAR BaseName[18];
    L_CHAR SysLog;
    L_CHAR Sync;
    L_CHAR Log;
    L_CHAR Os;
    L_WORD DefCharSet;
    L_WORD UseCharSet;
    L_WORD Reserved;
    L_CHAR UseCharSetName[MAX_ID_LEN];
} OPEN_DESC;

Описание полей структуры OPEN_DESC приведено в таблице 6.

Объем выдаваемой информации определяется длиной буфера RowBuf, которая устанавливается в поле LnBufRow контрольного блока CBL.

Если произошла ошибка при поиске запрашиваемой кодировки, и кодировка была изменена, то в поле Flags структуры (таблица 6) устанавливается флаг 0x01.

Таблица 6. Описание полей структуры OPEN_DESC
Поле структурыОписание
VerMajor Старший номер версии СУБД ЛИНТЕР, для которой построена БД
VerMinor Младший номер версии СУБД ЛИНТЕР, для которой построена БД
VerBuild Номер сборки версии СУБД ЛИНТЕР
Flags Флаги БД (таблица 7)
DBFlags Атрибуты БД
MaxRecSize Предельная длина записи в таблице БД
BaseName[18] Имя БД
SysLog

Признак активности системного журнала:

0 – журнал не ведется;

1 – журнал ведется.

Sync

 Признак синхронизации ввода/вывода (устанавливается при запуске СУБД ключом [NO]SYNC):

0 – синхронизация отменена;

1 – синхронизация установлена.

Примечание

Только для Windows-платформы.

Log

Признак ведения файла-протокола (устанавливается при запуске СУБД ключом [NO]LOG):

0 – протокол не ведется;

1 – протокол ведется.

Os Идентификатор операционной системы (приложение 2)
DefCharSet Идентификатор кодовой страницы по умолчанию для БД, заданный запросом set database default character set
UseCharSet Идентификатор установленной кодовой страницы канала
Reserved Резерв
UseCharSetName Имя установленной кодовой страницы канала

Таблица 7. Флаги БД
ФлагЗначениеОписание
OPENDESC_CSET_CHANGED 0x01Установленная кодовая страница не найдена. Используется кодовая страница по умолчанию.
OPENDESC_PASS_EXTERNAL 0x02 Пароль пользователю был задан администратором СУБД, и пользователь должен его сменить (при первом соединении с БД с помощью команды ALTER USER IDENTIFIED BY). До того, как произойдет смена пароля, доступ к БД будет запрещен.
OPENDESC_PASSLIFEEND 0x04

Флаг говорит о том, что «время жизни» у пароля истекло, и пользователь должен его сменить с помощью команды

ALTER USER IDENTIFIED BY. До смены пароля все другие запросы будут заблокированы (доступ запрещен).


Описание

В контрольном блоке (поле NumChan ) устанавливается номер открытого канала.

Для идентификации и аутентификации пользователя с использованием Kerberos-сервера необходимо:

  • перед запуском клиентского приложения получить Kerberos-тикет автоматически при входе в ОС либо с использованием специального программного обеспечения (см. документы «СУБД ЛИНТЕР. Запуск и останов СУБД ЛИНТЕР в среде ОС Windows» и «СУБД ЛИНТЕР. Запуск и останов СУБД ЛИНТЕР в среде ОС UNIX, QNX»);

  • использовать пустое имя пользователя или задать режим идентификации и аутентификации по Kerberos-протоколу установкой глобального флага ICR_FORCE_KRB (с помощью переменной окружения LINTER_KRB или функции интерфейса нижнего уровня inter_control) либо для всех соединений клиентского приложения, либо только для соединения, выполняемого по данной команде OPEN.

Пример идентификации и аутентификации по Kerberos-протоколу приведен в приложении 14.

Примечание

Асинхронное выполнение OPEN с идентификацией и аутентификацией по Kerberos-протоколу не поддерживается.

Коды завершения
Код Описание
NOFREEKAN Нет свободных каналов для организации соединения
ERRPASSWORD

Зарегистрированному пользователю в данный момент по каким-либо причинам запрещен доступ к БД

(например, работа вне установленного времени расписания)

Invalid_User_Name Указано имя незарегистрированного в БД пользователя
Invalid_User_Passwd Указан неправильный пароль зарегистрированного пользователя
Пример формирования команды
#include <string.h>
#include <stdlib.h>
#include "inter.h"

L_LONG LinterOPEN(TCBL * pCBL, L_CHAR * Name_Pass, L_CHAR * Node, L_WORD Prior, L_LONG PrzExe)
  {
  memcpy(pCBL->Command, "OPEN", 4);
  if (strlen(Node) > MAX_NODE_LEN)
    {
    return SQLLONGID;
    }
  memset(pCBL->Node, 0, MAX_NODE_LEN);
  memcpy(pCBL->Node, Node, strlen(Node));
  pCBL->PrzExe = PrzExe;
  pCBL->Prior = Prior;
  pCBL->PrzExe &= ~Q_ASYNC;
  inter(pCBL, Name_Pass, NULL, NULL, NULL);
  return pCBL->CodErr;
  }

Примеры использования команды
  1. #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include "inter.h"
    #include "exlib.h"
    
    
    #ifndef WINCE
    int    main()
    #else
    int    exopen()
    #endif
      {
      TCBL    CBLconnect;
      L_CHAR    Name_Pass[] = "SYSTEM/MANAGER";
      L_CHAR    Node[] = "        ";
      L_WORD    Priority = 0;
      L_LONG  PrzExe = M_EXCLUSIVE | Q_ENCODE | M_BINARY;
      L_LONG  Err;
    
      memset(&CBLconnect,0,sizeof(TCBL));
      Err = LinterOPEN(&CBLconnect, Name_Pass, Node, Priority, PrzExe);
      if (Err != NORMAL)
        PrintError(&CBLconnect);
      printf("Connect to RDBMS Linter\n");
    
      printf("End Example\n");
    
      return 0;
      }
  2. В приложении 6 приведен пример работы с двумя ядрами СУБД.

Заметили ошибку?
Выделите текст и нажмите Ctrl + Enter