учебники, программирование, основы, введение в,

 

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

Общие сведения о разработке приложений для WebSphere MQ
В большинстве приложений, работающих с WebSphere MQ, решаются такие задачи как: чтение сообщений из базы данных (БД) и запись их в очередь; чтение сообщений из очереди и запись их в БД; и то и другое одновременно. В более редких случаях, например, для задач мониторинга осуществляется чтение параметров объектов WebSphere MQ в частности Current Depth, Channel Status, Message Count, Last Message Date/Time и т.п.
Для задач чтения/записи сообщений в очередь ведется работа непосредственно с сообщениями.
Заголовок сообщения (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

В теле сообщения поля не имеют имен и идут в порядке перечисления в. без разделителей (разделители могут быть использованы, но тогда длина сообщения увеличится). Числа (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 и др.
Для программирования приложений, работающих с 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.

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

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

Синтаксис:
MQCONN (QmgrName, Hconn, CompCode, Reason)
где:


QmgrNam

-

имя менеджера очередей, к которому производиться подключение (латинские буквы, цифры, символы "_", "/", ".", "%" ).

Hconn

-

идентификатор связи (connection handle) с менеджером очередей

CompCode

-

код завершения, принимающий одно из трех значений: MQCC_OK, MQCC_WARNING, MQCC_FAILED

Reason

-

код ошибки, детализирующий код завершения.

Результат работы функции – установление связи с менеджером очередей и возвращение уникального идентификатора связи Hconn с менеджером. Имя QmgrNam может быть опущено (строка со значением Null или пробел), тогда обращение к менеджеру очередей на данном компьютере происходит по умолчанию. Одно из основных назначений функции – проверка авторизации пользователя (приложение работает под определенным пользователем с идентификатором userid, который может быть не авторизован для работы с данным менеджером или его объектами).

  1. 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 представлена в.
Опции объекта (переменная 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"  и объекта MQOD - в главе "MQOD – Object descriptor". Как правило, значений опций по умолчанию для 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. Структура объекта 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

Как видно из из имени поля MQMD можно извлечь всевозможные атрибуты заголовка сообщений.
GetMsgOpts – опции для функции MQGET - MQGMO (Get-message options), поля структуры которой приведены в. Наиболее часто используемые опции для управления 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".
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

-

код ошибки, детализирующий код завершения.

  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)

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

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

Синтаксис:
MQCLOSE (Hconn, Hobj, Options,
CompCode, Reason)
где:


Hconn

-

идентификатор связи (connection handle) с менеджером очередей

Hobj

-

идентификатор связи с объектом

ObjDesc

-

описание объекта MQOD

Options

-

опции объекта

CompCode

-

код завершения

Reason

-

код ошибки, детализирующий код завершения.

  1. 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 содержит значения, приведенные в, и может быть использована в тексте следующим образом: MQBO MyBO = {MQBO_DEFAULT};

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

Синтаксис:
MQCMIT (Hconn, CompCode, Reason)
Комментарии в данном случае излишни.

  • MQBACK - функция, которая указывает на то, что всем сообщениям, прочитанным и записанным с момента открытия транзакции, дается задний ход, то есть производится откат транзакции. Все сообщения, помещенные в очередь, удаляются из нее. Все сообщения, прочитанные из очереди, восстанавливаются в очереди (становятся доступными). Как правило, при чтении сообщения удаляются из очереди или помечаются как транзакционные и становятся не доступными (uncommitted messages), если прошла команда MQBEGIN.

Синтаксис:
MQBACK (Hconn, CompCode, Reason)
Работа функций MQBEGIN, MQCMIT и MQBACK будет на примере продемонстрирована в.
Следующие группы функций позволяют считывать и модифицировать атрибуты 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". Работа функций 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".

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

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

 

 
На главную | Содержание | < Назад....Вперёд >
С вопросами и предложениями можно обращаться по nicivas@bk.ru. 2013 г.Яндекс.Метрика