Интеграция приложений на основе WebSphere MQ
Лекция #8: Программный интерфейс MQI. Основные функции В лекции излагаются основы программирования приложений, работающих с WebSphere MQ. Описывается синтаксис функций интерфейса очередей сообщений MQI (Message Queue Interface) и основные опции для работы с объектами. К данной лекции можно будет периодически возвращаться как к справочному руководству по функциям WebSphere MQ при разработке приложений. Синтаксис функций является универсальным для любых языков программирования. Приводится аргументация того факта, что в данной книге примеры программ даются на языке С.
### Общие сведения о разработке приложений для WebSphere MQ В большинстве приложений, работающих с WebSphere MQ, решаются такие задачи как: чтение сообщений из базы данных (БД) и запись их в очередь; чтение сообщений из очереди и запись их в БД; и то и другое одновременно. В более редких случаях, например, для задач мониторинга осуществляется чтение параметров объектов WebSphere MQ в частности Current Depth, Channel Status, Message Count, Last Message Date/Time и т.п. Для задач чтения/записи сообщений в очередь ведется работа непосредственно с сообщениями. На рис.8.1 показана структура одного из таких сообщений. Рис. 8.1. Структура сообщения Заголовок сообщения (Message Header) несет в себе служебную информацию: идентификационный номер сообщения (Message ID); идентификатор пользователя, пославшего сообщение; формат, длину, кодировку, тип сообщения, дату и время отправки и т.д. Данные в сообщении (Message Data) на уровне приложений разделяются на поля. В спецификации приложений записывается структура сообщения, например, в табл.8.1.
Таблица 8.1.
Имя поля | Длина (байты) | Примечание
--- | --- | ---
Name | 50 | Для заполнения поля Account_Name таблицы Account
Account | 32 | Для заполнения поля Account таблицы Account
ClientNo | 32 | Для заполнения поля ClientNo таблицы Account
Detail | 4 | Для заполнения поля Detail таблицы Account
Account_Date | 10 | Дата в формате 'YYYY-MM-DD' для заполнения поля Account_Date таблицы Account
Account_Time | 8 | Время в формате 'HH-MM-SS' для заполнения поля Account_Time таблицы Account
Comment | 150 | Для заполнения поля Comment таблицы Account
В теле сообщения поля не имеют имен и идут в порядке перечисления в таблице 8.1. без разделителей (разделители могут быть использованы, но тогда длина сообщения увеличится). Числа (Integer, Long) записываются в символьном формате. По WebSphere MQ интерфейсу (канал и соответствующие очереди) могут передаваться сообщения одного или нескольких типов, например, информация о клиентах, счетах и проводках. Для обработки сообщения большое значение имеет поле заголовка MSGTYPE, определяющее тип сообщения. Каждому типу сообщения соответствует своя структура данных сообщения (Message Data). По типу сообщения программа определяет, по какой ветви программы осуществлять разбор сообщения. С одной стороны, не целесообразно увеличивать число интерфейсов и, соответственно, число WebSphere MQ объектов и обрабатывающих программ, однако практические неудобства могут сказаться, если число WebSphere MQ объектов перевалит за несколько сотен и они все будут использоваться одновременно на недостаточно мощной технике. С другой стороны, программирование и внедрение программ облегчается, если на один тип сообщения создается один интерфейс и одна программа. Оптимальное решение следует искать где-то посередине между этими двумя подходами. К вопросам унификации интерфейсов следует вернуться (это будет сделано при рассмотрении одновременной работы WebSphere MQ и баз данных), так как создание и сопровождение нескольких сотен похожих программ для работы WebSphere MQ может вызвать серьезные затруднения. Основу для программирования приложений, работающих с WebSphere MQ, предоставляет интерфейс очередей сообщений MQI (Message Queue Interface). Приложения для работы с WebSphere MQ, создаваемые пользователем, могут использовать следующие группы функций MQI: MQCONN, MQCONNХ и MQDISC. Эти функции обеспечивают подключение приложения к менеджеру очередей и отключение его. MQOPEN и MQCLOSE функции открывают и закрывают подключение к очередям, с которыми работает приложение. MQPUT и MQPUT1 функции обеспечивают помещение сообщений в очередь. MQGET функция поддерживает просмотр, извлечение и удаление сообщений из очереди. MQINQ функция позволяет запросить атрибуты WebSphere MQ объекта. MQSET функция устанавливает атрибуты очереди, но атрибуты других типов WebSphere MQ объектов не могут быть изменены. MQBEGIN, MQCMIT, MQBACK. Эти функции обеспечивают работу с WebSphere MQ транзакциями (открытие транзакции, закрытие и "откат" транзакции). Таким образом, обобщенная структура программа для работы с WebSphere MQ на уровне блоков может быть представлена в виде следующей последовательности псевдокода:
Блок 1 MQCONN
Блок 2 MQOPEN
Блок 3 MQBEGIN
Блок 4 MQGET
Блок 5 SQL UPDATE, SQL SELECT
Блок 6 MQPUT
Блок 7 Если нет ошибок - MQCMIT, в противном случае MQBACK
Блок 8 MQCLOSE
Блок 9 MQDISC
1. Разработка приложений на основе WebSphere MQ может осуществляться на платформах: UNIX (AIX, HP_UX, Linux, Solaris), Windows, OS/390, OS400, OS/2 Warp и др. Полный список поддерживаемых платформ можно найти на сайте ИБМ: http://www.ibm.com/software/ts/mqseries/library/#announce Для программирования приложений, работающих с WebSphere MQ, предлагается инструментарий на различных языках: C (для всех платформ), C++ (для большинства операционных систем), Visual Basic (для систем Windows), COBOL, Assembler (для мэйн-фреймов ИБМ с операционной системой z/OS), RPG, PL/I (для систем с z/OS, OS/2 Warp, VSE/ESA, Windows), TAL (для систем с Compaq NonStop Kernel) и другие средства. В WebSphere MQ для приложений на C++ в среде Windows следует редактировать (линковать) разрабатываемую программу с библиотекой MQI в дополнение к библиотекам операционной системы: mqm.Lib для WebSphere MQ Server для 32-bit C mqic.Lib для WebSphere MQ Client для 16-bit C mqic32.Lib для WebSphere MQ Client для 32-bit C В качестве заголовочных файлов следует использовать cmqc.h или cmqcfc.h Библиотека MQI обеспечивает реализацию функций WebSphere MQ. Список библиотек на других платформах, необходимых для разработки приложений на основе WMQ, можно найти в документации. Следует упомянуть об интерфейсе приложений для передачи сообщений AMI (Application Messaging Interface), который является более простым и высокоуровневым интерфейсом, чем MQI. И хотя AMI имеет некоторые ограничения по сравнению с MQI, его функции достаточно эффективны для большинства пользователей. AMI поддерживает два типа моделей для программирования приложений: точка-точка, издатель-подписчик. Интерфейс AMI существует для языков C, C++ и Java, работающих в операционных системах: OS/400, AIX, HP-UX, Solaris, Microsoft Windows и z/OS. В дальнейшем при описании функций интерфейса MQI будут использованы общие для всех функций два типа параметров: идентификатор (handle) и код возврата (return сode). При подключении к менеджеру очередей должен быть создан уникальный идентификатор этого менеджера для данного приложения, который называется идентификатором связи Hconn (connection handle). Идентификатор Hconn возвращается функциями MQCONN или MQCONNХ и передается во все другие функции как входной параметр. При работе с объектом WebSphere MQ должен также существовать уникальный идентификатор, называемый идентификатором объекта (object Handle). Этот идентификатор определяется функций MQOPEN при открытии объекта и возвращается как Hobj. Программа передает идентификатор объекта как входной параметр при вызове функций MQPUT, MQGET, MQINQ, MQSET или MQCLOSE. Код завершения (completion code) и код ошибки (reason code) возвращаются как выходные параметры в каждой функции. Совместно они называются кодами возврата (return codes) и показывают результат выполнения функции. Код завершения возвращается либо как MQCC_OK или MQCC_FAILED, отображая успешное или ошибочное выполнение функции, соответственно. Иногда возвращается промежуточное значение MQCC_WARNING как предупреждение о неполном завершении. MQCC_OK всегда соответствует Reason code = 0. MQCC_WARNING может сопутствовать, например, Reason code = 2002, это говорит о том, что приложение уже подключено. MQCC_FAILED обязательно имеет детализацию, например: Reason code = 2058 - менеджер с данным именем неизвестен или недоступен, Reason code = 2035 - нет прав доступа и т.д. Программа может и должна использовать код ошибки в процессе обработки. Например, при определенном коде ошибки программа может выдать сообщение пользователю с предложением изменить входные данные и после этого повторить вызов функции либо вернуть сообщение пользователю. Коды возврата подробно описаны в книге WebSphere MQ Messages [7]. ### Основные функции WebSphere MQ MQCONN - функция подключения приложения к менеджеру очередей. Синтаксис:
       MQCONN (QmgrName, Hconn, CompCode, Reason)
   где:
   QmgrNam | - | имя менеджера очередей, к которому производиться подключение (латинские буквы, цифры, символы "_", "/", ".", "%" ).
   Hconn | - | идентификатор связи (connection handle) с менеджером очередей
   CompCode | - | код завершения, принимающий одно из трех значений: MQCC_OK, MQCC_WARNING, MQCC_FAILED
   Reason | - | код ошибки, детализирующий код завершения.
2. Результат работы функции – установление связи с менеджером очередей и возвращение уникального идентификатора связи Hconn с менеджером. Имя QmgrNam может быть опущено (строка со значением Null или пробел), тогда обращение к менеджеру очередей на данном компьютере происходит по умолчанию. Одно из основных назначений функции – проверка авторизации пользователя (приложение работает под определенным пользователем с идентификатором userid, который может быть не авторизован для работы с данным менеджером или его объектами). MQOPEN – функция, открывающая подключение к очередям, с которыми работает приложение. Синтаксис:
       MQOPEN (Hconn, ObjDesc, Options, Hobj,
               CompCode, Reason)
   где:
   Hconn | - | идентификатор связи (connection handle) с менеджером очередей
   ObjDesc | - | описание объекта MQOD
   Options | - | опции объекта MQOO
   Hobj | - | идентификатор связи с объектом
   CompCode | - | код завершения, принимающий одно из трех значений: MQCC_OK – успешное завершение, MQCC_WARNING – предупреждение, MQCC_FAILED – ошибочный вызов
   Reason | - | код ошибки, детализирующий код завершения.
   Результат работы функции – возвращение уникального идентификатора связи Hobj с "открытым" объектом WebSphere MQ, то есть очередью, с которой установлена связь. Описание объекта MQOD – это ссылка на структуру объекта из библиотеки WebSphere MQ. Структура MQOD представлена в таблице 8.2. Опции объекта (переменная MQLONG): MQOO_BROWSE* – просмотр объекта, MQOO_INPUT* – объект открыт для помещения сообщений, MQOO_OUTPUT – объект открыт для извлечения сообщений, MQOO_INQUIRE - объект открыт для извлечения атрибутов, MQOO_SET - объект открыт для изменения атрибутов и др. Опции объекта со звездочками задаются, как правило, в виде развернутых констант: MQOO_INPUT_AS_Q_DEF - открытие очереди на основе ее определения; MQOO_INPUT_SHARED - открытие очереди для одновременного доступа нескольких приложений; MQOO_INPUT_EXCLUSIVE - открытие очереди для эксклюзивного доступа одному приложению; MQOO_BROWSE - открытие очереди для просмотра/чтения сообщений с возможностью дальнейшего использования детализирующих опций MQGMO_BROWSE_FIRST, MQGMO_BROWSE_NEXT, MQGMO_BROWSE_MSG_UNDER_CURSOR функции MQGET; MQOO_OUTPUT - открытие очереди для записи сообщений. Описание всех опций MQOO дано в главе "MQOPEN – Open object" [14] и объекта MQOD - в главе "MQOD – Object descriptor" [14]. Как правило, значений опций по умолчанию для MQOPEN вполне достаточно для программирования стандартных приложений для WebSphere MQ.
   Таблица 8.2. Структура объекта MQOD
   Имя поля MQOD | Тип поля | Имя константы | Значение по умолчанию
   --- | --- | --- | ---
   StrucId | MQCHAR4 | MQOD_STRUC_ID | 'ODbb'
   Version | MQLONG | MQOD_VERSION_1 | 1
   ObjectType | MQLONG | MQOT_Q | 1
   ObjectName | MQCHAR48 | Нет | Строка со значением Null или пробел
   ObjectQMgrName | MQCHAR48 | Нет | Строка со значением Null или пробел
   DynamicQName | MQCHAR48 | Нет | 'CSQ.*' на z/OS; 'AMQ.*' в противном случае
   AlternateUserId | MQCHAR12 | Нет | Строка со значением Null или пробел
   RecsPresent | MQLONG | Нет | 0
   KnownDestCount | MQLONG | Нет | 0
   UnknownDestCount | MQLONG | Нет | 0
   InvalidDestCount | MQLONG | Нет | 0
   ObjectRecOffset | MQLONG | Нет | 0
   ResponseRecOffset | MQLONG | Нет | 0
   ObjectRecPtr None | MQPTR | Нет | Указатель со значением Null
   ResponseRecPtr | MQPTR | Нет | Указатель со значением Null
   AlternateSecurityId | MQBYTE40 | MQSID_NONE | Nulls
   ResolvedQName | MQCHAR48 | Нет | Строка со значением Null или пробел
   ResolvedQMgrName | MQCHAR48 | Нет | Строка со значением Null или пробел
1. MQGET - функция для просмотра, извлечение и удаление сообщений из очереди. Синтаксис:
       MQGET (Hconn, Hobj, MsgDesc, GetMsgOpts,
              BufferLength,Buffer, DataLength,
              CompCode, Reason)
   где:
   Hconn | - | идентификатор связи с менеджером очередей, полученный от MQCONN
   Hobj | - | идентификатор объекта, полученный от MQOPEN
   MsgDesc | - | описание сообщения MQMD
   GetMsgOpts | - | опции объекта MQGMO для чтения сообщений
   BufferLength | - | длина буфера Buffer, в который считывается сообщение
   Buffer | - | буфер, в который считывается сообщение
   DataLength | - | длина сообщения
   CompCode | - | код завершения, принимающий одно из трех значений: MQCC_OK, MQCC_WARNING, MQCC_FAILED
   Reason | - | код ошибки, детализирующий код завершения.
   Hconn и Hobj – это идентификаторы, полученные от MQCONN и MQOPEN, соответственно. Описание сообщения MQMD – это ссылка на структуру объекта из библиотеки WebSphere MQ. Эта структура записывается следующим образом (табл.8.3).
   Таблица 8.3. Структура объекта MQMD
   Имя поля MQMD | Тип поля | Имя константы | Значение по умолчанию
   --- | --- | --- | ---
   StrucId | MQCHAR4 | MQMD_STRUC_ID | 'MDbb'
   Version | MQLONG | MQMD_VERSION_1 | 1
   Report | MQLONG | MQRO_NONE | 0
   MsgType | MQLONG | MQMT_DATAGRAM | 8
   Expiry | MQLONG | MQEI_UNLIMITED | MQEI_UNLIMITED
   Feedback | MQLONG | MQFB_NONE | 0
   Encoding | MQLONG | MQENC_NATIVE | В зависимости от среды
   CodedCharSetId | MQLONG | MQCCSI_Q_MGR | 0
   Format | MQCHAR8 | MQFMT_NONE | Пробел
   Priority | MQLONG | MQPRI_PRIORITY_AS_Q_DEF | -1
   Persistence | MQLONG | MQPER_PERSISTENCE_AS_Q_DEF | 2
   MsgId | MQBYTE24 | MQMI_NONE | Nulls
   CorrelId | MQBYTE24 | MQCI_NONE | Nulls
   BackoutCount | MQLONG | Нет | 0
   ReplyToQ | MQCHAR48 | Нет | Строка со значением Null или пробел
   ReplyToQMgr | MQCHAR48 | Нет | Строка со значением Null или пробел
   UserIdentifier | MQCHAR12 | Нет | Строка со значением Null или пробел
   AccountingToken | MQBYTE32 | MQACT_NONE | Nulls
   ApplIdentityData | MQBYTE32 | Нет | Строка со значением Null или пробел
   PutApplType | MQLONG | MQAT_NO_CONTEXT | 0
   PutApplName | MQCHAR28 | Нет | Строка со значением Null или пробел
   PutDate | MQCHAR8 | Нет | Строка со значением Null или пробел
   PutTime | MQCHAR8 | Нет | Строка со значением Null или пробел
   ApplOriginData | MQCHAR4 | Нет | Строка со значением Null или пробел
   GroupId | MQBYTE24 | MQGI_NONE | Nulls
   MsgSeqNumber | MQLONG | Нет | 1
   Offset | MQLONG | Нет | 0
   MsgFlags | MQLONG | MQMF_NONE | 0
   OriginalLength | MQLONG | MQOL_UNDEFINED | -1
   Как видно из табл.8.3 из имени поля MQMD можно извлечь всевозможные атрибуты заголовка сообщений. GetMsgOpts – опции для функции MQGET - MQGMO (Get-message options), поля структуры которой приведены в таблице 8.4. Наиболее часто используемые опции для управления MQGET: MQGMO_WAIT - определяет время ожидания функцией поступления новых сообщений в зависимости от значения в WaitInterval, заданногов мсек. MQGMO_NO_WAIT немедленно возвращает управление, если нет больше сообщений в очереди. MQGMO_BROWSE_FIRST - определяет, что читается первое сообщение в очереди. MQGMO_BROWSE_NEXT - определяет, что читается сообщение из текущей позиции. MQGMO_BROWSE_MSG_UNDER_CURSOR - определяет, что читается сообщение под курсором. MQGMO_LOGICAL_ORDER - определяет, что сообщения читаются в логическом порядке. Если опция опущена, то сообщения читаются в физическом порядке. MQGMO_FAIL_IF_QUIESCING - выдает ошибку, если менеджер не доступен. MQGMO_SYNCPOINT (MQGMO_NO_SYNCPOINT) - означает установку (отмену установки) контрольной точки (syncpoint control) на данном сообщении. MQGMO_ACCEPT_TRUNCATED_MSG - указывает, что допускается отсечение данных сообщения, например, если DataLength для реального сообщения больше BufferLength. Все опции MQGMO даны в главе "MQGET – Get message" [14]. BufferLength – длина в байтах области буфера Buffer, в который считывается сообщение (переменная типа MQLONG). Максимальная длина сообщений 100Мбт, длина по умолчанию 4Мбт, реальная длина большинства сообщений не более 10Кбт. Buffer - буфер, в который считывается сообщение. DataLength – длина сообщения в байтах (переменная MQLONG). Если DataLength для реального сообщения больше BufferLength, то часть сообщения может быть потеряна в зависимости от опции MQGMO_ACCEPT_TRUNCATED_MSG. CompCode, Reason – это стандартные возвращаемые параметры, упомянутые выше и не требующие детальных пояснений.
   Таблица 8.4. Поля структуры MQGMO
   Имя поля MQGMO | Тип поля | Описание поля | Имя константы | Значение по умолчанию
   --- | --- | --- | --- | ---
   StrucId | MQCHAR4 | Идентификатор структуры | MQGMO_STRUC_ID | 'GMOb'
   Version | MQLONG | Номер версии структуры | MQGMO_VERSION_1 | 1
   Options | MQLONG | Опции для управления MQGET | MQGMO_NO_WAIT | 0
   WaitInterval | MQLONG | Интервал ожидания (Wait interval) WaitInterval | None | 0
   Signal1 | MQLONG | Сигнал | Нет | Указатель Null на z/OS; 0 в ост. случаях
   Signal2 | MQLONG | Идентификатор сигнала | Нет | 0
   ResolvedQName | MQCHAR48 | Разрешенное имя очереди назначения (destination queue) | Нет | Строка string или пробел
   MatchOptions | MQLONG | Опции управления критериями выбора, используемыми MQGET | MQMO_MATCH_MSG_ID + MQMO_MATCH_CORREL_ID | 3
   GroupStatus | MQCHAR | Флаг, индицирующий, что извлеченное сообщение находиться в группе сообщений | MQGS_NOT_IN_GROUP | 'b'
   SegmentStatus | MQCHAR | Флаг, индицирующий, что извлеченное сообщение является сегментом логического сообщения | MQSS_NOT_A_SEGMENT | 'b'
   Segmentation | MQCHAR | Флаг, индицирующий, что допускается дальнейшая сегментация для извлеченного сообщения | MQSEG_INHIBITED | 'b'
   Reserved1 | MQCHAR | Резервное | Нет | 'b'
   MsgToken | MQBYTE16 | Маркер сообщения (Message token) | MQMTOK_NONE | Nulls
   ReturnedLength | MQLONG | Возвращаемая длина сообщения в байтах | MQRL_UNDEFINED | -1
1. MQPUT – функция для записи сообщений в очередь. Синтаксис:
       MQPUT (Hconn, Hobj, MsgDesc, PutMsgOpts,
              BufferLength, Buffer, CompCode, Reason)
   где:
   Hconn | - | идентификатор связи с менеджером очередей, полученный от MQCONN
   Hobj | - | идентификатор объекта, полученный от MQOPEN
   MsgDesc | - | описание сообщения MQMD
   PutMsgOpts | - | опции MQPMO для записи сообщений
   BufferLength | - | длина буфера Buffer, откуда пишется сообщение. Значение 0 является действительным и показывает, что сообщение не содержит данных.
   Buffer | - | буфер, из которого пишется сообщение
   CompCode | - | код завершения, принимающий одно из трех значений: MQCC_OK, MQCC_WARNING, MQCC_FAILED
   Reason | - | код ошибки, детализирующий код завершения.
   Параметры Hconn, Hobj, MsgDesc, BufferLength, Buffer, CompCode, Reason – такие же, как и в функции MQGET. Исключение составляет PutMsgOpts – опция MQPMO (Put-message options), служащая для того, чтобы положить сообщение в очередь. Поля структуры MQPMO приведены в таблице 8.5.
   Таблица 8.5. Поля структуры MQPMO
   Имя поля MQPMO | Тип поля | Описание поля | Имя константы | Значение по умолчанию
   --- | --- | --- | --- | ---
   StrucId | MQCHAR4 | Идентификатор структуры | MQPMO_STRUC_ID | 'PMOb'
   Version | MQLONG | Номер версии структуры | MQPMO_VERSION_1 | 1
   Options | MQLONG | Опции для управления MQPUT и MQPUT1 | MQPMO_NONE | 0
   Timeout | MQLONG | Зарезервировано | Нет | -1
   Context | MQHOBJ | Идентификатор объекта входной очереди | Нет | 0
   KnownDestCount | MQLONG | Число сообщений, посланное успешно в локальную очередь | Нет | 0
   UnknownDestCount | MQLONG | Число сообщений, посланное успешно в удаленную очередь | Нет | 0
   InvalidDestCount | MQLONG | Число сообщений, которые возможно не посланы | Нет | 0
   ResolvedQName | MQCHAR48 | Разрешенное имя очереди назначения | Нет | Строка Null или пробел
   ResolvedQMgrName | MQCHAR48 | Разрешенное имя менеджера назначения | Нет | Строка Null или пробел
   RecsPresent | MQLONG | Число записей помещенных сообщений или ответных записей в настоящее время | Нет | 0
   PutMsgRecFields | MQLONG | Флаг, индицирующий, что MQPMR поле присутствует | MQPMRF_NONE | 0
   PutMsgRecOffset | MQLONG | Погашение записи первого помещенного сообщения с момента старта MQPMO | Нет | 0
   ResponseRecOffset | MQLONG | Погашение записи первого ответа с момента старта MQPMO | Нет | 0
   PutMsgRecPtr | MQPTR | Адрес записи первого помещенного в очередь сообщения | Нет | Указатель Null
   ResponseRecPtr | MQPTR | Адрес записи первого ответа | Нет | Указатель Null
2. Среди опций для управления MQPUT следует назвать: MQPMO_NEW_MSG_ID - генерирует новый идентификатор сообщения MQPMO_NEW_CORREL_ID - генерирует новый корреляционный идентификатор и заменяет поле CorrelId в опции MQMD этим идентификатором. MQPMO_LOGICAL_ORDER - определяет, что сообщения в группах и сегментах пишутся в логическом порядке. MQPMO_FAIL_IF_QUIESCING - выдает ошибку, если менеджер не доступен. MQPMO_SYNCPOINT (MQPMO_NO_SYNCPOINT) - означает установку (отмену установки) контрольной точки (syncpoint control) на данном сообщении. MQ_MSG_HEADER_LENGTH - определяется для очереди передачи (transmission queue) Полный список опций MQPMO дан в главе "MQPUT – Put message" [14]. Функция MQPUT может положить сообщение как в локальную (local queue), так и в удаленную очередь (remote queue). MQGET считывает сообщения только из локальной очереди локального менеджера очередей, но не может читать сообщения на удаленном менеджере. MQCLOSE – функция, закрывающая подключение к очереди, с которой работает приложение. Синтаксис:
       MQCLOSE (Hconn, Hobj, Options,
                CompCode, Reason)
   где:
   Hconn | - | идентификатор связи (connection handle) с менеджером очередей
   Hobj | - | идентификатор связи с объектом
   ObjDesc | - | описание объекта MQOD
   Options | - | опции объекта
   CompCode | - | код завершения
   Reason | - | код ошибки, детализирующий код завершения.
3. MQDISC - функция для отключения приложения от менеджера очередей Синтаксис:
       MQDISC (Hconn, CompCode, Reason)
   где:
   Hconn | - | идентификатор связи (connection handle) с менеджером очередей
   CompCode | - | код завершения
   Reason | - | код ошибки
- Для работы приложений в условиях промышленной эксплуатации необходимо использовать дополнительные функции WebSphere MQ. ### Дополнительные функции WebSphere MQ Одним из важнейших приемов прикладного программирования для WebSphere MQ является использование транзакций, аналогичных транзакциям в базах данных. С помощью функций MQBEGIN, MQCMIT, MQBACK можно открыть транзакцию, завершить транзакцию успешно и откатить транзакцию, соответственно. В этом механизме прослеживается полная аналогия с транзакциями в базах данных. Программирование с использованием WebSphere MQ транзакций позволяет создавать надежные программы. MQBEGIN - функция, которая открывает WebSphere MQ транзакцию, координирует работу менеджера очередей и может использовать внешние ресурсы менеджера. Синтаксис:
      MQBEGIN (Hconn, BeginOptions,
               CompCode, Reason)
  где:
  Hconn | - | идентификатор связи (connection handle) с менеджером очередей
  BeginOptions | - | опции MQBEGIN
  CompCode | - | код завершения
  Reason | - | код ошибки, детализирующий код завершения.
  Здесь BeginOptions дает ссылку на структуру MQBO (Begin options), поля которой показаны в таблице 8.6
  Таблица 8.6. Поля структуры MQBO
  Имя поля MQBO | Тип поля | Имя поля | Имя константы | Значение константы
  --- | --- | --- | --- | ---
  StrucId | MQCHAR4 | Идентификатор структуры | MQBO_STRUC_ID | 'BObb'
  Version | MQLONG | Номер версии структуры | MQBO_VERSION_1 | 1
  Options | MQLONG | Опции для управления MQBO | MQBO_NONE | 0
- На языке С макропеременная MQBO_DEFAULT содержит значения, приведенные в табл.8.6, и может быть использована в тексте следующим образом: MQBO MyBO = {MQBO_DEFAULT}; MQCMIT – функция, которая указывает на то, что все сообщения, прочитанные и записанные с момента открытия транзакции, становятся постоянными, то есть транзакция успешно завершена. Сообщения, помещенные в очередь как часть блока сообщений, становятся доступными всем приложениям. Сообщения, прочитанные из очереди как часть блока сообщений, удаляются из очереди. Синтаксис:
      MQCMIT (Hconn, CompCode, Reason)
- Комментарии в данном случае излишни. MQBACK - функция, которая указывает на то, что всем сообщениям, прочитанным и записанным с момента открытия транзакции, дается задний ход, то есть производится откат транзакции. Все сообщения, помещенные в очередь, удаляются из нее. Все сообщения, прочитанные из очереди, восстанавливаются в очереди (становятся доступными). Как правило, при чтении сообщения удаляются из очереди или помечаются как транзакционные и становятся не доступными (uncommitted messages), если прошла команда MQBEGIN. Синтаксис:
      MQBACK (Hconn, CompCode, Reason)
- Работа функций MQBEGIN, MQCMIT и MQBACK будет на примере продемонстрирована в лекции 9. Следующие группы функций позволяют считывать и модифицировать атрибуты WebSphere MQ объектов, а также предоставляют дополнительный сервис. MQINQ – функция, которая возвращает массив цифр и множество символьных строк, содержащих параметры объекта. В качестве объектов могут выступать очередь, процесс, именованный список (namelist), менеджер очередей. Синтаксис:
      MQINQ (Hconn, Hobj, SelectorCount, Selectors,
             IntAttrCount, IntAttrs,
             CharAttrLength, CharAttrs,
             CompCode, Reason)
  где:
  Hconn | - | идентификатор связи с менеджером очередей, полученный от MQCONN
  Hobj | - | идентификатор объекта, полученный от MQOPEN
  SelectorCount | - | Счетчик атрибутов, которые должны быть извлечены (от 0 до 256)
  Selectors | - | Массив значений атрибутов, т.е. чисел или символов, которые должны быть извлечены
  IntAttrCount | - | Счетчик цифровых атрибутов
  IntAttrs | - | Массив цифровых атрибутов
  CharAttrLength | - | Длина буфера символьных атрибутов
  CharAttrs | - | Буфер значений символьных атрибутов
  CompCode | - | код завершения
  Reason | - | код ошибки, детализирующий код завершения.
- Комментарии. Буфер CharAttrs будет содержать значения символьных атрибутов в том же порядке, как перечислены атрибуты в Selectors. Многочисленные имена извлекаемых атрибутов приведены в главе "MQINQ – Inquire object attributes" [14]. Работа функций MQINQ и MQSET будет продемонстрирована позже на примере. MQSET – функция, изменяющая атрибуты объекта, представленного своим идентификатором. Объектом может быть только очередь. Синтаксис (аналогичен MQINQ):
      MQSET (Hconn, Hobj, SelectorCount, Selectors,
             IntAttrCount, IntAttrs,
             CharAttrLength, CharAttrs,
             CompCode, Reason)
  где:
  Hconn | - | идентификатор связи с менеджером очередей, полученный от MQCONN
  Hobj | - | идентификатор объекта, полученный от MQOPEN
  SelectorCount | - | Счетчик атрибутов, которые должны быть установлены (от 0 до 256)
  Selectors | - | Массив значений атрибутов, т.е. чисел или символов, которые должны быть установлены
  IntAttrCount | - | Счетчик цифровых атрибутов
  IntAttrs | - | Массив цифровых атрибутов
  CharAttrLength | - | Длина буфера символьных атрибутов
  CharAttrs | - | Буфер значений символьных атрибутов
  CompCode | - | код завершения
  Reason | - | код ошибки, детализирующий код завершения.
- Комментарии. Буфер CharAttrs должен содержать значения символьных атрибутов для записи в том же порядке, как перечислены атрибуты в Selectors. Имена устанавливаемых атрибутов приведены в главе "MQSET – Set object attributes" [14]. MQCONNХ – функция, которая обеспечивает подключение приложения к менеджеру очередей. Синтаксис:
      MQCONNХ (QMgrName, ConnectOpts, Hconn,
               CompCode, Reason)
- Функция MQCONNХ отличается от MQCONN наличием параметра ConnectOpts для контроля процесса подключения к менеджеру очередей и позволяет установить дополнительные опции. Опции MQCNO_STANDARD_BINDING и MQCNO_FASTPATH_BINDING служат для стандартного или быстрого установления связи. Опции MQCNO_HANDLE_SHARE_NONE, MQCNO_HANDLE_SHARE_BLOCK, MQCNO_HANDLE_SHARE_NO_BLOCK позволяют осуществлять управление идентификаторами связи при работе с разными процессами (threads). Опции SSLConfigPtr и SSLConfigOffset используются, когда приложение осуществляет вызов MQCONNХ через WebSphere MQ клиента по протоколу TCP/IP. Более подробно эти опции описаны в главе "MQCNO – Connect options" [14]. MQPUT1 – функция, которая помещает одно сообщение в очередь, при этом очередь не должна быть открыта. Функция MQPUT1 по сравнению с MQPUT не требует команды MQOPEN и MQCLOSE. Синтаксис:
      MQPUT1 (Hconn, ObjDesc, MsgDesc, PutMsgOpts,
              BufferLength, Buffer, CompCode,
              Reason)
Как следствие такого определения функции вместо параметра Hobj для MQPUT в MQPUT1 используется параметр ObjDesc, как и в функции MQOPEN. На этом обзор основных и дополнительных функций WebSphere MQ закончен. Теперь можно начинать писать первые приложения для WebSphere MQ, что и будет сделано в следующей лекции. В заключении следует отметить, что разработчикам приложений необходимо выбирать язык программирования исходя из решаемой задачи и требований на создаваемое ПО. Если приложение должно работать с WebSphere MQ в режиме промышленной эксплуатации при достаточно высоких требованиях на производительность, то рекомендуется использовать С, С++. Если приложение работает с WebSphere MQ в тестовом режиме без ограничений на производительность, то вполне подойдут Visual Basic 6.0 или Power Builder 6.0. Известны случаи, когда приложение, написанное на Visual Basic 6.0 или Power Builder 6.0 и работающее постоянно с WebSphere MQ, начинало наращивать используемую оперативную память, и разработчики этих программ не могли понять причину ошибки и устранить ее. Приложение, написанное на С++ и реализующее тот же алгоритм, не имеет подобного дефекта. Красивые интерфейсы при работе с WebSphere MQ требуются не так часто. Кроме того, следует отметить, что приложение на C/С++ обеспечивает обработку более 400 Persistent сообщений/секунду при длине сообщения 1Кбайт, в то время как приложение с тем же алгоритмом обработки на Visual Basic - не более 150 сообщений/секунду на компьютере INTEL Pentium 1.8Ггц. Все это объясняет тот факт, что в данной книге примеры программ даются на языке С.

© Макушкин В.А., Володичев Д.С. Все права защищены.