Интеграция приложений на основе WebSphere MQ

Программный интерфейс MQI. Основные функции

Разбить на страницы
Показывать лекцию целиком

Общие сведения о разработке приложений для 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.

Имя поля Длина (байты) Примечание
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

    Разработка приложений на основе 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) и показывают результат выполнения функции. Код завершения возвращается либо как .

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

  • MQCONN - функция подключения приложения к менеджеру очередей.

    Синтаксис:

    MQCONN (QmgrName, Hconn, CompCode, Reason)

    где:

    QmgrNam - имя менеджера очередей, к которому производиться подключение (латинские буквы, цифры, символы "_", "/", ".", "%" ).
    Hconn - идентификатор связи (connection handle) с менеджером очередей
    CompCode - код завершения, принимающий одно из трех значений: MQCC_OK, MQCC_WARNING, MQCC_FAILED
    Reason - код ошибки, детализирующий код завершения.

    Результат работы функции – установление связи с менеджером очередей и возвращение уникального идентификатора связи   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 - открытие очереди для записи сообщений.
    •

    Описание всех опций и объекта . Как правило, значений опций по умолчанию для MQOPEN вполне достаточно для программирования стандартных приложений для WebSphere MQ.

    Структура объекта 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 или пробел
  • 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).

    Структура объекта 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.
    •

    Все опции .

    BufferLength – длина в байтах области буфера Buffer, в который считывается сообщение (переменная типа MQLONG ). Максимальная длина сообщений 100Мбт, длина по умолчанию 4Мбт, реальная длина большинства сообщений не более 10Кбт.

    Buffer - буфер, в который считывается сообщение.

    DataLength – длина сообщения в байтах (переменная MQLONG ).

    Если DataLength для реального сообщения больше BufferLength, то часть сообщения может быть потеряна в зависимости от опции MQGMO_ACCEPT_TRUNCATED_MSG.

    CompCode, Reason – это стандартные возвращаемые параметры, упомянутые выше и не требующие детальных пояснений.

    Поля структуры 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
  • 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.

    Поля структуры 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

    Среди опций для управления 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)
    •

    Полный список опций .

    Функция MQPUT может положить сообщение как в локальную (local queue), так и в удаленную очередь (remote queue). MQGET считывает сообщения только из локальной очереди локального менеджера очередей, но не может читать сообщения на удаленном менеджере.

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

    Синтаксис:

    MQCLOSE (Hconn, Hobj, Options, 
         CompCode, Reason)

    где:

    Hconn - идентификатор связи (connection handle) с менеджером очередей
    Hobj - идентификатор связи с объектом
    ObjDesc - описание объекта MQOD
    Options - опции объекта
    CompCode - код завершения
    Reason - код ошибки, детализирующий код завершения.
  • 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

    Поля структуры 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 - код ошибки, детализирующий код завершения.

    Комментарии. Буфер . Работа функций 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 - код ошибки, детализирующий код завершения.

    Комментарии. Буфер .

  • 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).

    Опции .

  • 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Ггц. Все это объясняет тот факт, что в данной книге примеры программ даются на языке С.

    Страницы:

    Общие сведения о разработке приложений для 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.

    Имя поля Длина (байты) Примечание
    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

    Разработка приложений на основе 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) и показывают результат выполнения функции. Код завершения возвращается либо как .

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

  • MQCONN - функция подключения приложения к менеджеру очередей.

    Синтаксис:

    MQCONN (QmgrName, Hconn, CompCode, Reason)

    где:

    QmgrNam - имя менеджера очередей, к которому производиться подключение (латинские буквы, цифры, символы "_", "/", ".", "%" ).
    Hconn - идентификатор связи (connection handle) с менеджером очередей
    CompCode - код завершения, принимающий одно из трех значений: MQCC_OK, MQCC_WARNING, MQCC_FAILED
    Reason - код ошибки, детализирующий код завершения.

    Результат работы функции – установление связи с менеджером очередей и возвращение уникального идентификатора связи   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 - открытие очереди для записи сообщений.
    •

    Описание всех опций и объекта . Как правило, значений опций по умолчанию для MQOPEN вполне достаточно для программирования стандартных приложений для WebSphere MQ.

    Структура объекта 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 или пробел
  • 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).

    Структура объекта 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.
    •

    Все опции .

    BufferLength – длина в байтах области буфера Buffer, в который считывается сообщение (переменная типа MQLONG ). Максимальная длина сообщений 100Мбт, длина по умолчанию 4Мбт, реальная длина большинства сообщений не более 10Кбт.

    Buffer - буфер, в который считывается сообщение.

    DataLength – длина сообщения в байтах (переменная MQLONG ).

    Если DataLength для реального сообщения больше BufferLength, то часть сообщения может быть потеряна в зависимости от опции MQGMO_ACCEPT_TRUNCATED_MSG.

    CompCode, Reason – это стандартные возвращаемые параметры, упомянутые выше и не требующие детальных пояснений.

    Поля структуры 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
  • 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.

    Поля структуры 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

    Среди опций для управления 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)
    •

    Полный список опций .

    Функция MQPUT может положить сообщение как в локальную (local queue), так и в удаленную очередь (remote queue). MQGET считывает сообщения только из локальной очереди локального менеджера очередей, но не может читать сообщения на удаленном менеджере.

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

    Синтаксис:

    MQCLOSE (Hconn, Hobj, Options, 
         CompCode, Reason)

    где:

    Hconn - идентификатор связи (connection handle) с менеджером очередей
    Hobj - идентификатор связи с объектом
    ObjDesc - описание объекта MQOD
    Options - опции объекта
    CompCode - код завершения
    Reason - код ошибки, детализирующий код завершения.
  • 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

    Поля структуры 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 - код ошибки, детализирующий код завершения.

    Комментарии. Буфер . Работа функций 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 - код ошибки, детализирующий код завершения.

    Комментарии. Буфер .

  • 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).

    Опции .

  • 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Ггц. Все это объясняет тот факт, что в данной книге примеры программ даются на языке С.

    Предыдущее занятие Следующее занятие
    Вернуться к учебному плану
    ^