Основные функции 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 - открытие очереди для записи сообщений.
- 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.
Описание всех опций MQOO дано в главе "MQOPEN – Open object" [14] и объекта MQOD - в главе "MQOD – Object descriptor" [14]. Как правило, значений опций по умолчанию для MQOPEN вполне достаточно для программирования стандартных приложений для WebSphere MQ.
| 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 или пробел |
Hconn и Hobj – это идентификаторы, полученные от MQCONN и MQOPEN, соответственно.
Описание сообщения MQMD – это ссылка на структуру объекта из библиотеки WebSphere MQ. Эта структура записывается следующим образом (табл.8.3).
| 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 |
GetMsgOpts – опции для функции MQGET - MQGMO (Get-message options), поля структуры которой приведены в таблице 8.4. Наиболее часто используемые опции для управления MQGET:
Все опции MQGMO даны в главе "MQGET – Get message" [14].
BufferLength – длина в байтах области буфера Buffer, в который считывается сообщение (переменная типа MQLONG). Максимальная длина сообщений 100Мбт, длина по умолчанию 4Мбт, реальная длина большинства сообщений не более 10Кбт.
Buffer - буфер, в который считывается сообщение.
DataLength – длина сообщения в байтах (переменная MQLONG).
Если DataLength для реального сообщения больше BufferLength, то часть сообщения может быть потеряна в зависимости от опции MQGMO_ACCEPT_TRUNCATED_MSG.
CompCode, Reason – это стандартные возвращаемые параметры, упомянутые выше и не требующие детальных пояснений.
| 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, Hobj, MsgDesc, BufferLength, Buffer, CompCode, Reason – такие же, как и в функции MQGET. Исключение составляет PutMsgOpts – опция MQPMO (Put-message options), служащая для того, чтобы положить сообщение в очередь. Поля структуры MQPMO приведены в таблице 8.5.Hconn - идентификатор связи с менеджером очередей, полученный от MQCONN Hobj - идентификатор объекта, полученный от MQOPEN MsgDesc - описание сообщения MQMD PutMsgOpts - опции MQPMO для записи сообщений BufferLength - длина буфера Buffer, откуда пишется сообщение. Значение 0 является действительным и показывает, что сообщение не содержит данных. Buffer - буфер, из которого пишется сообщение CompCode - код завершения, принимающий одно из трех значений: MQCC_OK, MQCC_WARNING, MQCC_FAILED Reason - код ошибки, детализирующий код завершения.
Таблица 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)
- 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 - код ошибки
Полный список опций MQPMO дан в главе "MQPUT – Put message" [14].
Функция MQPUT может положить сообщение как в локальную (local queue), так и в удаленную очередь (remote queue). MQGET считывает сообщения только из локальной очереди локального менеджера очередей, но не может читать сообщения на удаленном менеджере.
Для работы приложений в условиях промышленной эксплуатации необходимо использовать дополнительные функции WebSphere MQ.
