asyan.org
добавить свой файл
1

Технический центр РТС RTS PLAZA Online

RTS plaza Online


Содержание документа

1. Изменения 2

2. Назначение 2

3. Состав программного обеспечения RTS PLAZA Online 2

4. Режимы работы 2

5. Использование RTS plaza Online 3

6. Особенности запуска в локальном режиме 10

7. Особенности запуска в автономном режиме 10

8. Справочник 11

9. Примеры программ 26


1.Изменения





26.12.2002

Сомов Ю.И.

Исправлена ошибка в написании сообщений RTSONL_MSG_CONN_REPLBEGIN и RTSONL_MSG_CONN_REPLEND (пункт «8.4. Типы сообщений Сообщения, получаемые при работе с данными» стр 12).

Добавилось описание отправки асинхронного сообщения на любой адрес посредством функции rtsonlPostMsg (пункты «2. Назначение» стр 2, «5.4.2. Отправка сообщения и обработка ответа» стр 9, «8.5. Функции Отправка сообщения» стр15, изменился рисунок «Figure 7»).

Добавилось описание функции rtsonlCloseAsynch - Асинхронно завершает работу (пункт «8.5. Функции Основные функции» стр15)

2.Назначение


RTS PLAZA Online – интерфейс прикладного программирования, предназначеный для работы с базой данных Российской торговой системы (РТС). Он обеспечивает получение данных в режиме online из базы данных РТС и отправку сообщений в ядро РТС (или по другому адресу) - для использования собственными прикладными программами пользователя. Данный интерфейс базируется на внутренних интерфейсах программного обеспечения RTS PLAZA Workstation.

Источником данных является база данных, получаемая клиентской рабочей станцией RTS PLAZA Workstation. Возможно также получение данных с промежуточного сервера компании, после регистрации его компанией-участником РТС в соответствии с установленными правилами.


3.Состав программного обеспечения RTS PLAZA Online


В состав поставляемого программного обеспечения RTS PLAZA Online входят: динамическая библиотека RtsOnl.dll, примеры прикладных программ, описание интерфейса (настоящий документ) и описание структур базы данных и сообщений РТС ПЛАЗА.


4.Режимы работы


Программа пользователя, использующая RTS PLAZA Online может работать в двух режимах: "локальном" и "автономном".

В локальном режиме (см. Figure 1) программа пользователя (Info) работает параллельно с графическим интерфейсом пользователя (GUI) RTS PLAZA Workstation. При этом репликация и online-сообщения торговой системы (RTS) принимаются модулем DataServer (RTSDS.exe), отображаются GUI пользователя и одновременно поступают в программу пользователя через RTS PLAZA Online.



Figure 1

В "автономном" режиме (см. Figure 2) программа пользователя заменяет модуль GUI и, в частности, сама устанавливает соединение с РТС.



Figure 2

В обоих режимах необходимо наличие на рабочей станции клиента программного обеспечения RTS PLAZA Workstation, модули которого используются для работы RTS PLAZA Online.


5.Использование RTS plaza Online

5.1.Механизм получения сообщений


Для взаимодействия с РТС программе-клиенту необходимо обрабатывать получаемые от RTS PLAZA Online сообщения, которые бывают трех видов:

  • сообщения, относящиеся к системе в целом;

  • сообщения, относящиеся к схеме базы данных или к схеме отсылаемых сообщений;

  • сообщения, относящиеся к определенной таблице из базы данных.

Первые содержат информацию о наличии соединения с источником данных и состоянии сети. Вторые содержат информацию о структуре базы данных и отсылаемых сообщений. Третьи – о записях в определенных таблицах или о записях, полученных в результате выполнения запроса. Структура таблиц приведена в документе "Структура базы данных РТС ПЛАЗА", а отсылаемых сообщений – в документе "Сообщения РТС".

Для получения сообщений клиент должен зарегистрировать приемник сообщений одного из двух видов:

  • специальную callback-функцию;

  • идентификатор окна вместе с номером сообщения Win32.

Каждое сообщение имеет определенный тип и содержит список параметров, заданный как void** params. В сообщении для окна params передается как wParam. Для обращения к параметру с индексом n необходимо привести выражение params[n] к типу соответствующего параметра. Описание программного кода для регистрации приемников сообщений приведены в примерах готовых программ в разделе "Примеры программ".


5.2.Запуск и завершение работы


Для работы с RTS PLAZA Online необходимо:

  1. Установить путь к INI-файлу настроек работы коммуникационного сервера RTSComm (функция rtsonlSetIniPath).

  2. В случае автономного режима произвести аутентификацию доступа в РТС: ввести имя пользователя, пароль и дополнительный пароль (функция rtsonlIdentify).

  3. Зарегистрировать в качестве приемника сообщений функцию пользователя (функция rtsonlRegisterCallback) или окно (функция rtsonlRegisterWnd).

  4. Запустить RTS PLAZA Online (функция rtsonlOpen).

  5. При отсутствии необходимости дальнейшей работы с РТС остановить RTS PLAZA Online (функция rtsonlClose).

При выполнении описанных выше этапов приходят только системные сообщения:

RTSONL_MSG_LOGINOK

Login пользователя завершился успешно.

RTSONL_MSG_LOGINFAILED

Login пользователя завершился неудачно.

RTSONL_MSG_NETINTEGRITYOK

Сообщение о наличии соединения графического интерфейса рабочей станции пользователя (при локальном режиме работы) или программы пользователя (при автономном режиме работы) с сервером РТС.

RTSONL_MSG_NETINTEGRITYLOST

Сообщение о разрыве соединения.

RTSONL_MSG_DS_CONNECTED

Сообщение о наличии связи RTS PLAZA Online с модулем DataServer рабочей станции пользователя.

RTSONL_MSG_DS_DISCONNECTED

Сообщение о разрыве связи с модулем DataServer.

RTSONL_MSG_PING

Контрольное сообщение-таймер, приходящее два раза в секунду при отсутствии других сообщений.





Figure 3


5.3.Работа с данными


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

  • получение только схемы базы данных;

  • получение только данных, если пользователю известна структура базы данных;

  • получение схемы базы данных, а затем - получение данных.



Figure 4


5.3.1.Получение схемы базы данных


Cхема базы данных содержит список имен таблиц, имена столбцов и их формат данных.

Для получения и разбора схемы необходимо:

  1. Запустить процесс получения схемы (функция rtsonlOpenScheme или rtsonlOpenSchemeAsynch).

  2. Получить список таблиц базы данных (функция rtsonlGetTable).

  3. Получить список имен колонок для каждой таблицы (функция rtsonlTableGetColumn).

  4. Завершить работу со схемой (функция rtsonlCloseScheme). Выполнение этой команды обязательно.



Figure 5


5.3.2.Получение данных


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

Соединения подразделяются на:

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

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

Соединения имеют уникальный идентификатор (типа RTSONL_CONNID).

Для получения данных необходимо:

  1. Сформировать запрос открыв соединение (функция rtsonlOpenConnection, в параметрах которой задаются: тип соединения (динамическое или статическое), источник данных (имя таблицы, имя колонки, имя поля), устанавливаются необходимые фильтры и параметры сортировки).

  2. Завершить работу закрыв соединение (функция rtsonlCloseConnection).

Схема приходящих при работе соединения сообщений приведена на Figure 6.



Figure 6

В случае успешного установления соединения программа-клиент получает сообщение RTSONL_MSG_CONN_CONNECTED (1). В случае ошибки в параметрах соединения (например неправильно задано имя колонки) приходит сообщение RTSONL_MSG_CONN_ERROR (2).

После успешного установления соединения приходят сообщения RTSONL_MSG_CONN_CLEAR (3) об очистке данных, RTSONL_MSG_CONN_FORMAT (4), которое содержит форматы запрашиваемых данных.

Далее происходит передача данных (5), приходят сообщения RTSONL_MSG_CONN_ADDROW (6).

После окончания передачи всех запрошенных данных приходит сообщение RTSONL_MSG_CONN_SYNCHRONIZED (7).

Далее, в случае статического соединения, соединение закрывается (12).

В случае динамического соединения клиент продолжает получать изменения в данных в режиме online (8). При этом приходят сообщения RTSONL_MSG_CONN_UPDATEROW, RTSONL_MSG_CONN_ADDROW, RTSONL_MSG_CONN_DELETEROW (9).

При возникновении ошибок в передаче данных на любом из этапов (например, в случае кратковременной потери связи с модулем DataService) приходит сообщение RTSONL_MSG_CONN_DISCONNECTED (10). После возобновления связи происходит автоматическое восстановление соединения (11), полученные ранее данные стираются и передача данных возобновляется.

Примечание: В RtsOnl.dll версии 2.0.05 и выше добавлены сообщения от модуля DataServer (см. Режимы работы) о состоянии базы данных пользователя. Сообщение RTSONL_MSG_CONN_REPLBEGIN означает начало получения модулем DataServer реплики базы данных от торговой системы. Сообщение RTSONL_MSG_CONN_REPLEND означает, что репликация данных была успешно завершена и база данных клиента соответствует базе данных торговой системы.

Примечание: В RtsOnl.dll версии 2.0.23 и выше добавлены сообщения от модуля DataServer о начале и завершении транзакции (RTSONL_MSG_BEGINTRANS, RTSONL_MSG_COMMIT, RTSONL_MSG_ROLLBACK). Cообщение RTSONL_MSG_ROLLBACK уведомляет о возникновении ошибки в работе с DataServer. Для получения указанных сообщений необходимо задать в секции [online] ini-файла DataServer опцию send_txn_events=1 (По-умолчанию это значение равно 0 – сообщений не посылать).


5.4.Работа с отправляемыми сообщениями


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

  • получение только схемы сообщений;

  • получение схемы сообщений, а затем - отправка сообщений и обработка ответов.



Figure 7


5.4.1.Получение схемы сообщений


Cхема сообщений содержит список имен сообщений, имена полей и формат данных.

Для получения и разбора схемы необходимо:

  1. Запустить процесс получения схемы (функция rtsonlOpenMsgScheme или rtsonlOpenMsgSchemeAsynch).

  2. Получить список сообщений (функция rtsonlGetMsg).

  3. Получить список имен полей для каждого сообщения (функция rtsonlGetMsgField).

  4. Завершить работу со схемой (функция rtsonlCloseMsgScheme). Выполнение этой команды обязательно.



Figure 8


5.4.2.Отправка сообщения и обработка ответа


Синхронная отправка сообщения производится с помощью функции rtsonlSendMsg, в параметрах которой задаются: тип сообщения (т.е. его имя), имена полей и их значения. В случае успешной обработки сообщения функция возвращает TRUE; вызвав функцию rtsonlGetReplyName, можно узнать имя ответного сообщения, а rtsonlGetReplyValue предоставит текстовое значение для каждого поля ответного сообщения. Если же при обработке сообщения возникла ошибка (функция rtsonlSendMsg возвратила FALSE), то текст ошибки можно узнать, вызвав функцию rtsonlGetReplyError.

Асинхронная отправка сообщения производится с помощью функции rtsonlPostMsg, в параметрах которой задаются: тип сообщения (т.е. его имя), имена полей и их значения, а так же адрес получателя. В случае успешной отправки сообщения функция возвращает TRUE. Если же при отправке сообщения возникла ошибка (функция rtsonlPostMsg возвратила FALSE), то текст ошибки можно узнать, вызвав функцию rtsonlGetReplyError. Прихода ответного сообщения не ожидается.

Если необходимо посылать сообщения в формате XML, подписанные электронной подписью, следует перед вызовами функций rtsonlSendMsg или rtsonlPostMsg инициализировать криптосистему, вызвав функцию rtsonlInitCryptoSign, а после отправки всех подписанных сообщений – отключить криптосистему, вызвав функцию rtsonlCloseCryptoSign.


5.5.Дополнительные функции


В интерфейсе RTS PLAZA Online имеются дополнительные функции: rtsonlStringToDateTime, которая преобразует формат даты и времени и rtsonlPrintf для выдачи получаемых данных в окно консоли или log-файл, описанный в соответствующем ini-файле программы. Их описание приведено в разделе "Справочник".

6.Особенности запуска в локальном режиме


В локальном режиме программное обеспечение RTS PLAZA Workstation должно быть запущено до запуска программы пользователя, использующей RTS PLAZA Online, причем последнюю можно запускать из другого каталога.

Необходим также ini-файл с именем .ini, где info – имя программы пользователя.

Пример ini-файла программы пользователя для локального режима работы:

[COMMSERV]
LEVEL=1
LOGFILE=.log

[RPC]
SECTION=RPC*LRPC

[RPC*LRPC]
ENDPOINT=

[CONNECT]
PRIMARY=CONNECTLRPC
RETRYTIME=5

[CONNECTLRPC]
TYPE=RPC
SECTION=RPC*LRPC
ENDPOINT=GUI3

7.Особенности запуска в автономном режиме


Для работы в автономном режиме надо изменить настройку файла RTSWatch.ini. В разделе [GUI] переменной COMMANDLINE вместо RTSGUI.exe надо присвоить имя автономной программы пользователя. Необходим также ini-файл с именем .ini, где info – имя программы пользователя.

В случае работы в автономном режиме обязательно использование функции rtsonlIdentify для аутентификации доступа в РТС.

Пример ini-файла программы пользователя для автономного режима работы.

[COMMSERV]
LEVEL=1
LOGFILE=.log

[RPC]
SECTION=RPC*LRPC

[RPC*LRPC]
ENDPOINT=GUI3

[CONNECT]
PRIMARY=CONNECTROOT

[CONNECTROOT]
TYPE=WINSOCK
NETWORKADDRESS=rts.rtsnet.ru
REMOTEPORT=2041

8.Справочник

8.1.Типы данных


Идентификатор соединения:

typedef LONG RTSONL_CONNID;


Тип функции, получающей сообщения online (callback-функция):

typedef void (*RTSONL_CALLBACK)( UINT msgType, void** params );


Головная структура базы данных:

typedef struct

{

int version; //Номер версии базы данных

int tablesCount; //Количество таблиц

} RTSONL_DB_SCHEME;

Структура данных, описывающая одну таблицу базы данных:

typedef struct

{

char name[64]; //Имя таблицы

int columnsCount; //Количество колонок

} RTSONL_TABLE;

Структура данных, описывающая одну колонку таблицы базы данных:

typedef struct

{

char name[64]; //Имя колонки

char format[32]; //Формат данных

} RTSONL_COLUMN;


Головная структура схемы сообщений:

typedef struct

{

int version; //Номер версии схемы сообщений

int messagesCount; //Количество сообщений

} RTSONL_MSG_SCHEME;

Структура данных, описывающая одно сообщение:

typedef struct

{

char name[64]; //Имя сообщения

int fieldsCount; //Количество полей

} RTSONL_MSG;

Структура данных, описывающая одно поле сообщения:

typedef struct

{

char name[64]; //Имя поля

char format[32]; //Формат данных

} RTSONL_MSG_FIELD;


8.2.Соединения


Значение параметра type функции rtsonlOpenConnection:

RTSONL_OPEN_DYNAMIC //Динамическое соединение

RSTONL_OPEN_STATIC //Статическое соединение


8.3.Флаги


Значение параметра flags функции rtsonlOpenConnection, указывающих порядок перебора записей по индексу:

RTSONL_FLAGS_ENUM_DIRECTION_FORWARD

RTSONL_FLAGS_ENUM_DIRECTION_BACKWARD


8.4.Типы сообщений

Системные сообщения

RTSONL_MSG_LOGINOK

Параметры (params):
char* userName -имя пользователя

Login завершился успешно.
RTSONL_MSG_LOGINFAILED

Параметры (params):
char* reason -строка с причиной неудачи

Login завершился неудачно
RTSONL_MSG_NETINTEGRITYOK

Параметры (params):
char* loginExtraInfo -дополнительная информация о пользователе

Связь с сервером установлена.
RTSONL_MSG_NETINTEGRITYLOST

Параметры (params):
нет

Связь с сервером разорвана.
RTSONL_MSG_DS_CONNECTED

Параметры (params):
нет

Связь с модулем DataServer установлена.
RTSONL_MSG_DS_DISCONNECTED

Параметры (params):
нет

Связь с модулем DataServer разорвана.
RTSONL_MSG_PING

Параметры (params):
нет

Контрольное сообщение-таймер, приходящее 2 раза в секунду при отсутствии других сообщений.
RTSONL_MSG_TYMESYNC

Параметры (params):

SYSTEMTIME *pDateTime - год (4 цифры), месяц, день, час, минута, секунда, день недели

Сообщение, приходящее один раз в минуту (если был отправлен запрос на синхронизацию времени), содержащее метку времени.


Сообщения, получаемые при работе с данными

RTSONL_MSG_DB_SCHEME

Параметры (params):
RTSONL_DB_SCHEME*

Возвращает указатель на структуру базы данных в ответ на вызов функции rtsonlOpenSchemeAsynch (описана ниже)
RTSONL_MSG_CONN_CONNECTED

Параметры (params):
RTSONCONNID connID


Установлено соединения с иденитификатором connID.
RTSONL_MSG_CONN_DISCONNECTED

Параметры (params):
RTSONCONNID connID


Прервано соединение с иденитификатором connID.
RTSONL_MSG_CONN_ERROR

Параметры (params):
RTSONCONNID connID
char* errorText

Сообщение от DataServer об ошибке в параметрах соединения, errorText – дополнительная информация.
RTSONL_MSG_CONN_CLEAR

Параметры (params):
RTSONCONNID connID

Проведена очистка данных, полученных с помощью соединения connID.
RTSONL_MSG_CONN_FORMAT

Параметры (params):
RTSONCONNID connID
int columnsCount
char* format

Сообщение о формате получаемых данных.

connID – идентификатор соединения;

columnsCount – количество колонок в соединении, определяещее длину списков в собщениях RTSONL_MSG_CONN_ADDROW, RTSONL_MSG_CONN_UPDATEROW, RTSONL_MSG_CONN_DELETEROW;

format – формат данных (например "u4,c10,c255,d10.5").
RTSONL_MSG_CONN_ADDROW

Параметры (params):
RTSONCONNID connID
LONG rowID
список{ char* fieldValue }

Получена запись базы данных.

connID – идентификатор соединения;

rowID=id   идентификатор записи;

fieldValue - список, содержащий значения полей в текстовом виде.
RTSONL_MSG_CONN_UPDATEROW

Параметры (params):
RTSONCONNID connID
LONG rowID
список{ char* fieldValue }

Обновлена запись базы данных.

connID – идентификатор соединения;

rowID=id – идентификатор записи;

fieldValue - список, содержащий новые значения полей в текстовом виде.
RTSONL_MSG_CONN_DELETEROW

Параметры (params):
RTSONCONNID connID
LONG rowID
список{ char* fieldValue }

Удалена запись базы данных.

connID – идентификатор соединения,

rowID=id – идентификатор записи,

fieldValue - список, содержащий старые значения полей в текстовом виде.
RTSONL_MSG_CONN_SYNCHRONIZED

Параметры (params):
RTSONCONNID connID

Процедура получения данных с помощью соединения connID завершена.
RTSONL_MSG_CONN_REPLBEGIN

Параметры (params):
RTSONCONNID connID

Сообщение от DataServer о начале получения реплики таблицы базы данных из торговой системы
RTSONL_MSG_CONN_REPLEND

Параметры (params):
RTSONCONNID connID

Сообщение от DataServer о завершении получения реплики таблицы базы данных из торговой системы

Сообщения, получаемые при работе с отправляемыми сообщениями

RTSONL_MSG_MSG_SCHEME

Параметры (params):
RTSONL_MSG_SCHEME* scheme

Возвращает указатель на схему сообщений в ответ на вызов функции rtsonlOpenMsgSchemeAsynch (описана ниже). После окончания работы со схемой необходимо вызвать функцию rtsonlCloseMsgScheme.


8.5.Функции

Основные функции



rtsonlSetIniPath

void WINAPI rtsonlSetIniPath ( const char* iniPath )

Устанавливает файл настроек для работы коммуникационного сервера RTSComm.

Параметры:

iniPath – путь к ini-файлу.


rtsonlIdentify

BOOL WINAPI rtsonlIdentify ( const char* userName, const char* password, const char* extraPwd )

Аутентификацию доступа в РТС при автономного режима работы приложения, использующего RTS PLAZA Online. Если эта функция не была вызвана, используется локальный режим работы, требующий наличия другого приложения, работающего в автономном режиме (обычно это GUI - графическая оболочка RTS PLAZA Workstation).

Параметры:

userName – имя рабочей станции пользователя;

password – пароль;

extraPwd – дополнительный пароль (в данное время он должен принимать фиксированное значение "GUI3").

Результат:

TRUE - успешно;

NULL - ошибка.


rtsonlRegisterWnd

BOOL WINAPI rtsonlRegisterWnd ( HWND hwndCallback, UINT message )

Регистрирует окно, как получатель сообщений RTS PLAZA Online.

Параметры:

hwndCallback – идентификатор окна, которое будет получать сообщения;

message - номер windows-сообщения, которое будет получать окно.

Результат:

TRUE - успешно;

NULL - ошибка.


rtsonlRegisterCallback

BOOL WINAPI rtsonlRegisterCallback ( RTSONL_CALLBACK callback )

Регистрирует функцию, как получатель сообщений RTS PLAZA Online.

Параметры:

callback - указатель на функцию-получатель сообщений.

Результат:

TRUE - успешно;

NULL - ошибка.


rtsonlOpen

void WINAPI rtsonlOpen ( )

Начинает работу с RTS PLAZA Online.


rtsonlClose

void WINAPI rtsonlClose ( )

Завершает работу с RTS PLAZA Online.
rtsonlCloseAsynch

void WINAPI rtsonlCloseAsynch ( )

Асинхронно завершает работу с RTS PLAZA Online.


Получение схемы базы данных



rtsonlOpenScheme

RTSONL_DB_SCHEME* WINAPI rtsonlOpenScheme ( )

Синхронный запрос схемы базы данных. Функция не может быть вызвана из callback’а.

Результат:

!=NULL - указатель на схему;

NULL - ошибка.


rtsonlOpenSchemeAsynch

BOOL WINAPI rtsonlOpenSchemeAsynch ( )

Асинхронный запрос схемы базы данных. Функция может быть вызвана из callback’а. Указатель на структуру, описывающую базу данных, возвращается сообщением RTSONL_MSG_DB_SCHEME (описано выше).

Результат:

TRUE – запрос принят, надо ждать сообщение RTSONL_MSG_ DB_SCHEME;

FALSE – запрос не принят.


rtsonlCloseScheme

void WINAPI rtsonlCloseScheme ( RTSONL_DB_SCHEME* scheme )

Завершает работу со схемой базы данных.

Параметры:

scheme - указатель на схему.


rtsonlGetTable

RTSONL_TABLE* WINAPI rtsonlGetTable ( RTSONL_DB_SCHEME* scheme, int tableIndex )

Получает указатель на структуру, описывающую таблицу с индексом tableIndex.

Параметры:

table - указатель на схему;

tableIndex - индекс таблицы, может принимать значения от 0 до tablesCount из scheme.

Результат:

!=NULL - указатель на описание;

NULL - нет такого описания.


rtsonlTableGetColumn

RTSONL_COLUMN* WINAPI rtsonlTableGetColumn( RTSONL_TABLE* table, int columnIndex )

Получает указатель на структуру, описывающую колонку с индексом columnIndex.

Параметры:

table - указатель на таблицу;

columnIndex - индекс колонки, может принимать значения от 0 до columnsCount из table.

Результат:

!=NULL - указатель на описание;

NULL - нет такого описания.



Получение данных



rtsonlOpenConnection

RTSONL_CONNID WINAPI rtsonlOpenConnection ( int type, const char* tableName, const char* columns, const char* indexColumns, const char* recMin, const char* recMax, int flags )

Открывает соединение для получения данных.

Параметры:

type – тип соединения (RTSONL_OPEN_DYNAMIC или RSTONL_OPEN_STATIC);

tableName - название таблицы;

columns – список колонок в таблице, интересующих пользователя;

indexColumns – список колонок, соответствующий индексу id;

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

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

Возможные значения recMin и recMax:

а) значения колонок из indexColumns, разделенные символом "001";

b)" – нет ограничения.

flags - порядок перебора записей по индексу.

Результат:

!= 0 - идентификатор соединения;

0 - ошибка.


rtsonlGetNextConnectionID

RTSONL_CONNID WINAPI rtsonlGetNextConnectionID ()

Резервирование идентификатора соединения. Используется в паре с функцией rtsonlOpenConnectionEx. После окончания работы с соединением его необходимо закрыть с помощью функции rtsonlCloseConnection.

Результат:

!= 0 - идентификатор соединения;

0 - ошибка.


rtsonlOpenConnectionEx

RTSONL_CONNID WINAPI rtsonlOpenConnectionEx ( int type, const char* tableName, const char* columns, const char* indexColumns, const char* recMin, const char* recMax, int flags, RTSONL_CONNID userConnID )

Открывает зарезервированное соединение для получения данных.

Параметры:

type – см. rtsonlOpenConnection;

tableName – см. rtsonlOpenConnection;

columns – см. rtsonlOpenConnection;

indexColumns – см. rtsonlOpenConnection;

recMin – см. rtsonlOpenConnection;

recMax – см. rtsonlOpenConnection;

flags – см. rtsonlOpenConnection;

userConnID – требуемый идентификатор соединения (получается как результат вызова функции rtsonlGetNextConnectionID).

Результат:

!= 0 - идентификатор соединения, равный параметру userConnID;

0 - ошибка.


rtsonlCloseConnection

void WINAPI rtsonlCloseConnection ( RTSONL_CONNID conn )

Закрывает соединение.

Параметры:

conn – идентификатор соединения.


Получение схемы сообщений



rtsonlOpenMsgScheme

RTSONL_MSG_SCHEME* WINAPI rtsonlOpenMsgScheme ( )

Синхронный запрос схемы сообщений. Функция не может быть вызвана из callback’а. После окончания работы со схемой необходимо вызвать функцию rtsonlCloseMsgScheme.

Результат:

!=NULL - указатель на схему;

NULL - нет такой схемы.


rtsonlOpenMsgSchemeAsynch

BOOL WINAPI rtsonlOpenMsgSchemeAsynch ( )

Асинхронный запрос схемы сообщений. Функция может быть вызвана из callback’а. Указатель на структуру, описывающую схему, возвращается сообщением RTSONL_MSG_MSG_SCHEME (описано выше).

Результат:

TRUE – запрос принят, надо ждать сообщение RTSONL_MSG_MSG_SCHEME;

FALSE – запрос не принят.


rtsonlCloseMsgScheme

void WINAPI rtsonlCloseMsgScheme( RTSONL_MSG_SCHEME* scheme )

Завершает работу со схемой сообщений и с отправляемыми сообщениями.

Параметры:

scheme - указатель на схему.


rtsonlGetMsg

RTSONL_MSG* WINAPI rtsonlGetMsg ( RTSONL_MSG_SCHEME* scheme, int msgIndex )

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

Параметры:

scheme - указатель на схему;

msgIndex - индекс сообщения, может принимать значения от 0 до messagesCount из scheme.

Результат:

!=NULL - указатель на описание;

NULL - нет такого описания.


rtsonlFindMsg

RTSONL_MSG* WINAPI rtsonlFindMsg ( RTSONL_MSG_SCHEME* scheme, const char* msgName )

Поиск указателя на структуру, описывающую сообщение с именем msgName.

Параметры:

scheme - указатель на схему;

msgName - имя искомого сообщения.

Результат:

!=NULL - указатель на описание;

NULL - нет такого описания.


rtsonlGetMsgField

RTSONL_MSG_FIELD* WINAPI rtsonlGetMsgField ( RTSONL_MSG* msg, int fieldIndex )

Получает указатель на структуру, описывающую поле с индексом fieldIndex.

Параметры:

msg - указатель на сообщение;

fieldIndex - индекс поля, может принимать значения от 0 до fieldsCount из msg.

Результат:

!=NULL - указатель на описание;

NULL - нет такого описания.


rtsonlFindMsgField

RTSONL_MSG_FIELD* WINAPI rtsonlFindMsgField ( RTSONL_MSG* msg, const char* fieldName )

Поиск указателя на структуру, описывающую поле с именем fieldName.

Параметры:

msg - указатель на сообщение;

fieldName - имя искомого сообщения.

Результат:

!=NULL - указатель на описание;

NULL - нет такого описания.



Функции криптосистемы для отправки подписанных сообщений



rtsonlInitCryptoSign

BOOL WINAPI rtsonlInitCryptoSign (const char* key_dir, const char* cid, const char* from_address)

Инициализация криптосистемы перед отправкой подписанных сообщений.

Параметры:

key_dir – имя директории, в которой находится копия ключевой дискеты, или самой дискеты;

cid – идентификатор сертификата отправителя;

from_address – адрес отправителя.

Результат:

TRUE - Ok.

FALSE - ошибка, её текст можно узнать, вызвав функцию rtsonlGetReplyError.


rtsonlCloseCryptoSign

void WINAPI rtsonlCloseCryptoSign ( )

Отключение криптосистемы после отправки всех подписанных сообщений.



Отправка сообщения



rtsonlSendMsg

BOOL WINAPI rtsonlSendMsg (const RTSONL_MSG_SCHEME* scheme, const char* msgName, const char* fields, const char* fieldsValues )

Синхронная отправка сообщения. Функция не может быть вызвана из callback’а. Сообщение посылается на адрес "ROOT.master".

Параметры:

scheme - указатель на схему;

msgName - имя сообщения;

fields - список полей в сообщении, заполненных пользователем;

fieldsValues - список значений полей, соответствующий списку fields, через запятую. Если в значении поля встречается запятая “,” или обратная косая черта “\”, то перед ней долна быть поставлена обратная косая черта “\”:

"," -> "\," "\" -> "\\"

Результат:

TRUE - сообщение отправлено, ответное сообщение можно прочитать с помощью функций rtsonlGetReplyName и rtsonlGetReplyValue.

FALSE - при обработке сообщения возникла ошибка, а её текст можно узнать, вызвав функцию rtsonlGetReplyError.


rtsonlPostMsg

BOOL WINAPI rtsonlSendMsg (const RTSONL_MSG_SCHEME* scheme, const char* msgName, const char* fields, const char* fieldsValues, const char* address )

Асинхронная отправка сообщения. Функция может быть вызвана из callback’а.

Параметры:

scheme - указатель на схему;

msgName - имя сообщения;

fields - список полей в сообщении, заполненных пользователем;

fieldsValues - список значений полей, соответствующий списку fields, через запятую. Если в значении поля встречается запятая “,” или обратная косая черта “\”, то перед ней долна быть поставлена обратная косая черта “\”:

"," -> "\," "\" -> "\\"

address - адрес получателя сообщения.

Результат:

TRUE - сообщение отправлено.

FALSE - при отправке сообщения возникла ошибка, а её текст можно узнать, вызвав функцию rtsonlGetReplyError.


rtsonlGetReplyName

const char* WINAPI rtsonlGetReplyName ( )

Запрос имени ответного сообщения. Значение изменяется после каждого вызова rtsonlSendMsg.

Результат:

!=NULL - указатель на имя;

NULL - нет имени.


rtsonlGetReplyValue

const char* WINAPI rtsonlGetReplyValue ( const char* field )

Запрос значения поля из ответного сообщения. Значение изменяется после каждого вызова rtsonlSendMsg.

Параметры:

field - имя поля.

Результат:

!=NULL - указатель на значение в виде текста (запятая “,” и обратная косая черта “\” представляются без изменений, как есть; в отличие от параметра fieldsValues функции rtsonlSendMsg);

NULL - нет такого поля.


rtsonlGetReplyError

const char* WINAPI rtsonlGetReplyError ( )

Запрос текста ошибки обработки запроса. Значение изменяется после каждого вызова rtsonlSendMsg или rtsonlPostMsg.

Результат:

!=NULL - указатель на текст ошибки, может быть “\0”.


Дополнительные функции



rtsonlStringToDateTime

void WINAPI rtsonlStringToDateTime ( const char* dtText, SYSTEMTIME* pDateTime )

Преобразовывает текстовое представление даты или даты и времени в структуру SYSTEMTIME.

Параметры:

dtText - указатель на текст;

Возможные форматы даты и времени следующие:
null – не определено, ' ';
дата DDMMYYYY;
дата и время DDMMYYYYHHNNSS.

pDateTime - указатель на переменную, куда будет записано значение. Структура SYSTEMTIME определена в файле wtypes.h.


rtsonlPrintf

void WINAPIV rtsonlPrintf ( const char* format, ... )

Выводит данные на консоль или в файл, определенный пользователем.

Параметры аналогичны параметрам функции printf.

9.Примеры программ

9.1.Вывод данных на консоль


Имя

OnlCon.exe

Режим работы

локальный или автономный

Тип соединения

динамический

Приемник сообщений

callback-функция

Отображение информации

через консоль



В примере приводятся 2 варианта .ini файла, соответствующие двум режимам работы:

OnlConL.ini -для локального;

OnlConR.ini -для автономного.

Для запуска программы надо либо переименовать один из этих файлов, в зависимости от выбранного режима, в OnlCon.ini, либо задавать нужный ini-файл в командной строке.

Для правильного запуска этой программы в локальном режиме необходимо:

  1. Создать новый каталог, например OnlCon.

  2. Скопировать в него файлы OnlCon.exe, RtsOnl.dll и OnlConL.ini, переименовав его в OnlCon.ini.

  3. Скопировать туда же файл RTSComm.dll из каталога, в котором находится программное обеспечение RTS PLAZA Workstation.

  4. Запустить программное обеспечение RTS PLAZA Workstation (файл RTS.exe).

  5. Запустить файл OnlCon.exe.

Примечание: Можно запускать программу из каталога, в котором находится программное обеспечение RTS PLAZA Workstation. Для этого надо скопировать в данный каталог файлы OnlCon.ini, OnlCon.exe и RtsOnl.dll. Далее произвести действия 4. и 5.

В автономном режиме этой программе необходим файл OnlConR.ini и не надо запускать RTS PLAZA Workstation.

Исходный текст программы OnlCon.exe находится в файле OnlCon.cpp.


9.2.Получение схемы базы данных и её сохранение в файле


Имя

scheme.exe

Режим работы

локальный

Приемник сообщений

callback-функция

Отображение информации

запись в файл scheme.log

Для правильного запуска этой программы необходимо:

  1. Создать новый каталог, например Scheme.

  2. Скопировать в него файлы scheme.ini, scheme.exe и RtsOnl.dll.

  3. Скопировать туда же файл RTSComm.dll из каталога, в котором находится программное обеспечение RTS PLAZA Workstation.

  4. Запустить программное обеспечение RTS PLAZA Workstation.

  5. Запустить файл scheme.exe.

Примечание: Можно запускать программу из каталога, в котором находится программное обеспечение RTS PLAZA Workstation. Для этого надо скопировать в данный каталог файлы scheme.ini, scheme.exe и RtsOnl.dll. Далее произвести действия 4. и 5.

Исходный текст программы scheme.exe находится в файле scheme.cpp.


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


Имя

RTSExpo.exe

Режим работы

локальный

Приемник сообщений

callback-функция

Отображение информации

запись в базу данных пользователя под управлением MS SQL Server.

Для правильного запуска этой программы необходимо:

  1. Сначала создать новую пустую базу данных RTSExpo с помощью MS SQL Server.

  2. Затем необходимо задать имя источника данных (DSN): RtsExpo. Для этого надо вызвать из Control Panel (Панель Управления) ODBC и на закладке User DSN или System DSN, в зависимости от того для конкретного пользователя или для всех пользователей надо сделать доступным это имя, добавить, нажав кнопку Add, новый DSN. Из появившегося списка драйверов выберите SQL Server. Затем задайте "Data Source Name" = RtsExpo и, нажав на кнопку Select, выберите базу данных.

  3. Затем выполните команду создания структуры базы данных createdb.bat.
    ВНИМАНИЕ! В это время должна работать RTS PLAZA Workstation.
    После этого база данных готова к работе.

  4. RTSExpo.exe запускается при работающей RTS PLAZA Workstation. Если он работает некорректно (например, пуста какая-либо из таблиц доступ к данным которой с Вашей рабочей станции PLAZA обеспечен), пересоздайте структуру данных командой createdb.bat, затем снова запустите экспортер.

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


9.4.Получение схемы сообщений и отправка сообщения


Имя

SendMsg.exe

Режим работы

локальный или автономный

Приемник сообщений

callback-функция

Отображение информации

через консоль

Для правильного запуска этой программы необходимо:

  1. Создать новый каталог, например SendMsg.

  2. Скопировать в него файлы SendMsg.ini, SendMsg.exe и RtsOnl.dll.

  3. Скопировать туда же файл RTSComm.dll из каталога, в котором находится программное обеспечение RTS PLAZA Workstation.

  4. Запустить программное обеспечение RTS PLAZA Workstation.

  5. Запустить файл SendMsg.exe.

Примечание: Можно запускать программу из каталога, в котором находится программное обеспечение RTS PLAZA Workstation. Для этого надо скопировать в данный каталог файлы SendMsg.ini, SendMsg.exe и RtsOnl.dll. Далее произвести действия 4. и 5.

В качестве тестового сообщения посылается "MsgNews".

Исходный текст программы SendMsg.exe находится в файле SendMsg.cpp.


9.5.Выполнение пакета заданий на отправку сообщений


Имя

SendMsg_bat.exe

Режим работы

локальный или автономный

Отображение информации

через консоль

Для правильного запуска этой программы необходимо:

  1. Создать новый каталог, например SendMsg_bat.

  2. Скопировать в него файлы SendMsg_bat.txt, SendMsg_bat.ini, SendMsg_bat.exe и RtsOnl.dll.

  3. Скопировать туда же файл RTSComm.dll из каталога, в котором находится программное обеспечение RTS PLAZA Workstation.

  4. Запустить программное обеспечение RTS PLAZA Workstation.

  5. Запустить файл SendMsg_bat.exe.

Примечание: Можно запускать программу из каталога, в котором находится программное обеспечение RTS PLAZA Workstation. Для этого надо скопировать в данный каталог файлы SendMsg_bat.txt, SendMsg_bat.ini, SendMsg.exe и RtsOnl.dll. Далее произвести действия 4. и 5.

В качестве тестовых посылаются сообщения типа "MsgNews".

Исходный текст программы SendMsg_bat.exe находится в файле SendMsg_bat.cpp.



26.12.02 Copyright © 1998-2002 ТЦ РТС /