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

         

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


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




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

      Таблица 8.2. Структура объекта MQODИмя поля MQODТип поляИмя константыЗначение по умолчанию
      StrucIdMQCHAR4MQOD_STRUC_ID'ODbb'
      VersionMQLONGMQOD_VERSION_11
      ObjectTypeMQLONGMQOT_Q1
      ObjectNameMQCHAR48НетСтрока со значением Null или пробел
      ObjectQMgrNameMQCHAR48НетСтрока со значением Null или пробел
      DynamicQNameMQCHAR48Нет'CSQ.*' на z/OS; 'AMQ.*' в противном случае
      AlternateUserIdMQCHAR12НетСтрока со значением Null или пробел
      RecsPresentMQLONGНет0
      KnownDestCountMQLONGНет0
      UnknownDestCountMQLONGНет0
      InvalidDestCountMQLONGНет0
      ObjectRecOffsetMQLONGНет0
      ResponseRecOffsetMQLONGНет0
      ObjectRecPtr NoneMQPTRНетУказатель со значением Null
      ResponseRecPtrMQPTRНетУказатель со значением Null
      AlternateSecurityIdMQBYTE40MQSID_NONENulls
      ResolvedQNameMQCHAR48НетСтрока со значением Null или пробел
      ResolvedQMgrNameMQCHAR48НетСтрока со значением Null или пробел


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

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

      Таблица 8.3. Структура объекта MQMDИмя поля MQMDТип поляИмя константыЗначение по умолчанию
      StrucIdMQCHAR4MQMD_STRUC_ID'MDbb'
      VersionMQLONGMQMD_VERSION_11
      ReportMQLONGMQRO_NONE0
      MsgTypeMQLONGMQMT_DATAGRAM8
      ExpiryMQLONGMQEI_UNLIMITEDMQEI_UNLIMITED
      FeedbackMQLONGMQFB_NONE0
      EncodingMQLONGMQENC_NATIVEВ зависимости от среды
      CodedCharSetIdMQLONGMQCCSI_Q_MGR0
      FormatMQCHAR8MQFMT_NONEПробел
      PriorityMQLONGMQPRI_PRIORITY_AS_Q_DEF-1
      PersistenceMQLONGMQPER_PERSISTENCE_AS_Q_DEF2
      MsgIdMQBYTE24MQMI_NONENulls
      CorrelIdMQBYTE24MQCI_NONENulls
      BackoutCountMQLONGНет0
      ReplyToQMQCHAR48НетСтрока со значением Null или пробел
      ReplyToQMgrMQCHAR48НетСтрока со значением Null или пробел
      UserIdentifierMQCHAR12НетСтрока со значением Null или пробел
      AccountingTokenMQBYTE32MQACT_NONENulls
      ApplIdentityDataMQBYTE32НетСтрока со значением Null или пробел
      PutApplTypeMQLONGMQAT_NO_CONTEXT0
      PutApplNameMQCHAR28НетСтрока со значением Null или пробел
      PutDateMQCHAR8НетСтрока со значением Null или пробел
      PutTimeMQCHAR8НетСтрока со значением Null или пробел
      ApplOriginDataMQCHAR4НетСтрока со значением Null или пробел
      GroupIdMQBYTE24MQGI_NONENulls
      MsgSeqNumberMQLONGНет1
      OffsetMQLONGНет0
      MsgFlagsMQLONGMQMF_NONE0
      OriginalLengthMQLONGMQOL_UNDEFINED-1
      Как видно из табл.8.3 из имени поля MQMD можно извлечь всевозможные атрибуты заголовка сообщений.

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

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




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

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

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

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

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

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

        Таблица 8.4. Поля структуры MQGMOИмя поля MQGMOТип поляОписание поляИмя константыЗначение по умолчанию
        StrucIdMQCHAR4Идентификатор структурыMQGMO_STRUC_ID'GMOb'
        VersionMQLONGНомер версии структурыMQGMO_VERSION_11
        OptionsMQLONGОпции для управления MQGETMQGMO_NO_WAIT0
        WaitIntervalMQLONGИнтервал ожидания (Wait interval) WaitIntervalNone0
        Signal1MQLONGСигналНетУказатель Null на z/OS; 0 в ост. случаях
        Signal2MQLONGИдентификатор сигналаНет0
        ResolvedQNameMQCHAR48Разрешенное имя очереди назначения (destination queue)НетСтрока string или пробел
        MatchOptionsMQLONGОпции управления критериями выбора, используемыми MQGETMQMO_MATCH_MSG_ID + MQMO_MATCH_CORREL_ID3
        GroupStatusMQCHARФлаг, индицирующий, что извлеченное сообщение находиться в группе сообщенийMQGS_NOT_IN_GROUP'b'
        SegmentStatusMQCHARФлаг, индицирующий, что извлеченное сообщение является сегментом логического сообщенияMQSS_NOT_A_SEGMENT'b'
        SegmentationMQCHARФлаг, индицирующий, что допускается дальнейшая сегментация для извлеченного сообщенияMQSEG_INHIBITED'b'
        Reserved1MQCHARРезервноеНет'b'
        MsgTokenMQBYTE16Маркер сообщения (Message token)MQMTOK_NONENulls
        ReturnedLengthMQLONGВозвращаемая длина сообщения в байтах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Тип поляОписание поляИмя константыЗначение по умолчанию
        StrucIdMQCHAR4Идентификатор структурыMQPMO_STRUC_ID'PMOb'
        VersionMQLONGНомер версии структурыMQPMO_VERSION_11
        OptionsMQLONGОпции для управления MQPUT и MQPUT1MQPMO_NONE0
        TimeoutMQLONGЗарезервированоНет-1
        ContextMQHOBJИдентификатор объекта входной очередиНет0
        KnownDestCountMQLONGЧисло сообщений, посланное успешно в локальную очередьНет0
        UnknownDestCountMQLONGЧисло сообщений, посланное успешно в удаленную очередьНет0
        InvalidDestCountMQLONGЧисло сообщений, которые возможно не посланыНет0
        ResolvedQNameMQCHAR48Разрешенное имя очереди назначенияНетСтрока Null или пробел
        ResolvedQMgrNameMQCHAR48Разрешенное имя менеджера назначенияНетСтрока Null или пробел
        RecsPresentMQLONGЧисло записей помещенных сообщений или ответных записей в настоящее времяНет0
        PutMsgRecFieldsMQLONGФлаг, индицирующий, что MQPMR поле присутствуетMQPMRF_NONE0
        PutMsgRecOffsetMQLONGПогашение записи первого помещенного сообщения с момента старта MQPMOНет0
        ResponseRecOffsetMQLONGПогашение записи первого ответа с момента старта MQPMOНет0
        PutMsgRecPtrMQPTRАдрес записи первого помещенного в очередь сообщенияНетУказатель Null
        ResponseRecPtrMQPTRАдрес записи первого ответаНетУказатель 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" [14].

          Функция 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.


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







        Forekc.ru
        Рефераты, дипломы, курсовые, выпускные и квалификационные работы, диссертации, учебники, учебные пособия, лекции, методические пособия и рекомендации, программы и курсы обучения, публикации из профильных изданий