Основные функции 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, который может быть не авторизован для работы с данным менеджером или его объектами).

2. 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 - объект открыт для изменения атрибутов и др. Опции объекта со звездочками задаются, как правило, в виде развернутых констант:

   
   
3. MQOO_INPUT_AS_Q_DEF - открытие очереди на основе ее определения;
4. MQOO_INPUT_SHARED - открытие очереди для одновременного доступа нескольких приложений;
5. MQOO_INPUT_EXCLUSIVE - открытие очереди для эксклюзивного доступа одному приложению;
6. MQOO_BROWSE - открытие очереди для просмотра/чтения сообщений с возможностью дальнейшего использования детализирующих опций MQGMO_BROWSE_FIRST, MQGMO_BROWSE_NEXT, MQGMO_BROWSE_MSG_UNDER_CURSOR функции MQGET;
7. MQOO_OUTPUT - открытие очереди для записи сообщений.




Описание всех опций MQOO дано в главе "MQOPEN – Open object" [14] и объекта MQOD - в главе "MQOD – Object descriptor" [14]. Как правило, значений опций по умолчанию для MQOPEN вполне достаточно для программирования стандартных приложений для WebSphere MQ.

Таблица 8.2. Структура объекта MQODИмя поля MQODТип поляИмя константыЗначение по умолчанию

StrucId	MQCHAR4	MQOD_STRUC_ID	'ODbb'
Version	MQLONG	MQOD_VERSION_1	1
ObjectType	MQLONG	MQOT_Q	1
ObjectName	MQCHAR48	Нет	Строка со значением Null или пробел
ObjectQMgrName	MQCHAR48	Нет	Строка со значением Null или пробел
DynamicQName	MQCHAR48	Нет	'CSQ.*' на z/OS; 'AMQ.*' в противном случае
AlternateUserId	MQCHAR12	Нет	Строка со значением Null или пробел
RecsPresent	MQLONG	Нет	0
KnownDestCount	MQLONG	Нет	0
UnknownDestCount	MQLONG	Нет	0
InvalidDestCount	MQLONG	Нет	0
ObjectRecOffset	MQLONG	Нет	0
ResponseRecOffset	MQLONG	Нет	0
ObjectRecPtr None	MQPTR	Нет	Указатель со значением Null
ResponseRecPtr	MQPTR	Нет	Указатель со значением Null
AlternateSecurityId	MQBYTE40	MQSID_NONE	Nulls
ResolvedQName	MQCHAR48	Нет	Строка со значением Null или пробел
ResolvedQMgrName	MQCHAR48	Нет	Строка со значением Null или пробел



Hconn и Hobj – это идентификаторы, полученные от MQCONN и MQOPEN, соответственно.

Описание сообщения MQMD – это ссылка на структуру объекта из библиотеки WebSphere MQ. Эта структура записывается следующим образом (табл.8.3).

Таблица 8.3. Структура объекта MQMDИмя поля MQMDТип поляИмя константыЗначение по умолчанию

StrucId	MQCHAR4	MQMD_STRUC_ID	'MDbb'
Version	MQLONG	MQMD_VERSION_1	1
Report	MQLONG	MQRO_NONE	0
MsgType	MQLONG	MQMT_DATAGRAM	8
Expiry	MQLONG	MQEI_UNLIMITED	MQEI_UNLIMITED
Feedback	MQLONG	MQFB_NONE	0
Encoding	MQLONG	MQENC_NATIVE	В зависимости от среды
CodedCharSetId	MQLONG	MQCCSI_Q_MGR	0
Format	MQCHAR8	MQFMT_NONE	Пробел
Priority	MQLONG	MQPRI_PRIORITY_AS_Q_DEF	-1
Persistence	MQLONG	MQPER_PERSISTENCE_AS_Q_DEF	2
MsgId	MQBYTE24	MQMI_NONE	Nulls
CorrelId	MQBYTE24	MQCI_NONE	Nulls
BackoutCount	MQLONG	Нет	0
ReplyToQ	MQCHAR48	Нет	Строка со значением Null или пробел
ReplyToQMgr	MQCHAR48	Нет	Строка со значением Null или пробел
UserIdentifier	MQCHAR12	Нет	Строка со значением Null или пробел
AccountingToken	MQBYTE32	MQACT_NONE	Nulls
ApplIdentityData	MQBYTE32	Нет	Строка со значением Null или пробел
PutApplType	MQLONG	MQAT_NO_CONTEXT	0
PutApplName	MQCHAR28	Нет	Строка со значением Null или пробел
PutDate	MQCHAR8	Нет	Строка со значением Null или пробел
PutTime	MQCHAR8	Нет	Строка со значением Null или пробел
ApplOriginData	MQCHAR4	Нет	Строка со значением Null или пробел
GroupId	MQBYTE24	MQGI_NONE	Nulls
MsgSeqNumber	MQLONG	Нет	1
Offset	MQLONG	Нет	0
MsgFlags	MQLONG	MQMF_NONE	0
OriginalLength	MQLONG	MQOL_UNDEFINED	-1

Как видно из табл.8.3 из имени поля MQMD можно извлечь всевозможные атрибуты заголовка сообщений.

GetMsgOpts – опции для функции MQGET - MQGMO (Get-message options), поля структуры которой приведены в таблице 8.4. Наиболее часто используемые опции для управления MQGET:


8. MQGMO_WAIT - определяет время ожидания функцией поступления новых сообщений в зависимости от значения в WaitInterval, заданногов мсек. MQGMO_NO_WAIT немедленно возвращает управление, если нет больше сообщений в очереди.
9. MQGMO_BROWSE_FIRST - определяет, что читается первое сообщение в очереди.
10. MQGMO_BROWSE_NEXT - определяет, что читается сообщение из текущей позиции.
11. MQGMO_BROWSE_MSG_UNDER_CURSOR - определяет, что читается сообщение под курсором.
12. MQGMO_LOGICAL_ORDER - определяет, что сообщения читаются в логическом порядке. Если опция опущена, то сообщения читаются в физическом порядке.
13. MQGMO_FAIL_IF_QUIESCING - выдает ошибку, если менеджер не доступен.
14. MQGMO_SYNCPOINT (MQGMO_NO_SYNCPOINT) - означает установку (отмену установки) контрольной точки (syncpoint control) на данном сообщении.
15. MQGMO_ACCEPT_TRUNCATED_MSG - указывает, что допускается отсечение данных сообщения, например, если DataLength для реального сообщения больше BufferLength.




Все опции MQGMO даны в главе "MQGET – Get message" [14].

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

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

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

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

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

Таблица 8.4. Поля структуры MQGMOИмя поля MQGMOТип поляОписание поляИмя константыЗначение по умолчанию

StrucId	MQCHAR4	Идентификатор структуры	MQGMO_STRUC_ID	'GMOb'
Version	MQLONG	Номер версии структуры	MQGMO_VERSION_1	1
Options	MQLONG	Опции для управления MQGET	MQGMO_NO_WAIT	0
WaitInterval	MQLONG	Интервал ожидания (Wait interval) WaitInterval	None	0
Signal1	MQLONG	Сигнал	Нет	Указатель Null на z/OS; 0 в ост. случаях
Signal2	MQLONG	Идентификатор сигнала	Нет	0
ResolvedQName	MQCHAR48	Разрешенное имя очереди назначения (destination queue)	Нет	Строка string или пробел
MatchOptions	MQLONG	Опции управления критериями выбора, используемыми MQGET	MQMO_MATCH_MSG_ID + MQMO_MATCH_CORREL_ID	3
GroupStatus	MQCHAR	Флаг, индицирующий, что извлеченное сообщение находиться в группе сообщений	MQGS_NOT_IN_GROUP	'b'
SegmentStatus	MQCHAR	Флаг, индицирующий, что извлеченное сообщение является сегментом логического сообщения	MQSS_NOT_A_SEGMENT	'b'
Segmentation	MQCHAR	Флаг, индицирующий, что допускается дальнейшая сегментация для извлеченного сообщения	MQSEG_INHIBITED	'b'
Reserved1	MQCHAR	Резервное	Нет	'b'
MsgToken	MQBYTE16	Маркер сообщения (Message token)	MQMTOK_NONE	Nulls
ReturnedLength	MQLONG	Возвращаемая длина сообщения в байтах	MQRL_UNDEFINED	-1

1. MQPUT – функция для записи сообщений в очередь.
   
   Синтаксис:
   
   MQPUT (Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer, CompCode, Reason)
   
   
   
   где:
   
   

   Hconn	-	идентификатор связи с менеджером очередей, полученный от MQCONN
   Hobj	-	идентификатор объекта, полученный от MQOPEN
   MsgDesc	-	описание сообщения MQMD
   PutMsgOpts	-	опции MQPMO для записи сообщений
   BufferLength	-	длина буфера Buffer, откуда пишется сообщение. Значение 0 является действительным и показывает, что сообщение не содержит данных.
   Buffer	-	буфер, из которого пишется сообщение
   CompCode	-	код завершения, принимающий одно из трех значений: MQCC_OK, MQCC_WARNING, MQCC_FAILED
   Reason	-	код ошибки, детализирующий код завершения.

   Параметры Hconn, Hobj, MsgDesc, BufferLength, Buffer, CompCode, Reason – такие же, как и в функции MQGET. Исключение составляет PutMsgOpts – опция MQPMO (Put-message options), служащая для того, чтобы положить сообщение в очередь. Поля структуры MQPMO приведены в таблице 8.5.
   
   Таблица 8.5. Поля структуры MQPMOИмя поля MQPMOТип поляОписание поляИмя константыЗначение по умолчанию

   StrucId	MQCHAR4	Идентификатор структуры	MQPMO_STRUC_ID	'PMOb'
   Version	MQLONG	Номер версии структуры	MQPMO_VERSION_1	1
   Options	MQLONG	Опции для управления MQPUT и MQPUT1	MQPMO_NONE	0
   Timeout	MQLONG	Зарезервировано	Нет	-1
   Context	MQHOBJ	Идентификатор объекта входной очереди	Нет	0
   KnownDestCount	MQLONG	Число сообщений, посланное успешно в локальную очередь	Нет	0
   UnknownDestCount	MQLONG	Число сообщений, посланное успешно в удаленную очередь	Нет	0
   InvalidDestCount	MQLONG	Число сообщений, которые возможно не посланы	Нет	0
   ResolvedQName	MQCHAR48	Разрешенное имя очереди назначения	Нет	Строка Null или пробел
   ResolvedQMgrName	MQCHAR48	Разрешенное имя менеджера назначения	Нет	Строка Null или пробел
   RecsPresent	MQLONG	Число записей помещенных сообщений или ответных записей в настоящее время	Нет	0
   PutMsgRecFields	MQLONG	Флаг, индицирующий, что MQPMR поле присутствует	MQPMRF_NONE	0
   PutMsgRecOffset	MQLONG	Погашение записи первого помещенного сообщения с момента старта MQPMO	Нет	0
   ResponseRecOffset	MQLONG	Погашение записи первого ответа с момента старта MQPMO	Нет	0
   PutMsgRecPtr	MQPTR	Адрес записи первого помещенного в очередь сообщения	Нет	Указатель Null
   ResponseRecPtr	MQPTR	Адрес записи первого ответа	Нет	Указатель Null

   
   
   Среди опций для управления MQPUT следует назвать:
   
   
2. MQPMO_NEW_MSG_ID - генерирует новый идентификатор сообщения
3. MQPMO_NEW_CORREL_ID - генерирует новый корреляционный идентификатор и заменяет поле CorrelId в опции MQMD этим идентификатором.
4. MQPMO_LOGICAL_ORDER - определяет, что сообщения в группах и сегментах пишутся в логическом порядке.
5. MQPMO_FAIL_IF_QUIESCING - выдает ошибку, если менеджер не доступен.
6. MQPMO_SYNCPOINT (MQPMO_NO_SYNCPOINT) - означает установку (отмену установки) контрольной точки (syncpoint control) на данном сообщении.
7. MQ_MSG_HEADER_LENGTH - определяется для очереди передачи (transmission queue)


Полный список опций MQPMO дан в главе "MQPUT – Put message" [14].

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


8. MQCLOSE – функция, закрывающая подключение к очереди, с которой работает приложение.
   
   Синтаксис:
   
   MQCLOSE (Hconn, Hobj, Options, CompCode, Reason)
   
   где:
   
   

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

9. MQDISC - функция для отключения приложения от менеджера очередей
   
   Синтаксис:
   
   MQDISC (Hconn, CompCode, Reason)
   
   где:
   
   

   Hconn	-	идентификатор связи (connection handle) с менеджером очередей
   CompCode	-	код завершения
   Reason	-	код ошибки

Для работы приложений в условиях промышленной эксплуатации необходимо использовать дополнительные функции WebSphere MQ.


Содержание раздела

---

---