1. A API MQ — visão geral
Toda aplicação MQ segue o mesmo fluxo:
MQCONN → Conecta ao Queue Manager (obtém HCONN)
MQOPEN → Abre fila ou outro objeto (obtém HOBJ)
MQPUT → Envia mensagem para a fila aberta
MQGET → Lê mensagem da fila aberta
MQCLOSE → Fecha o objeto (libera HOBJ)
MQDISC → Desconecta do Queue Manager (libera HCONN)
Estruturas de dados usadas:
MQMD → Message Descriptor — metadados da mensagem
MQPMO → Put Message Options — opções de envio
MQGMO → Get Message Options — opções de recebimento
MQOD → Object Descriptor — descreve a fila a abrir
Cada chamada retorna dois códigos:
- CompCode — 0=OK, 1=Warning, 2=Failed
- Reason — código numérico que detalha o resultado (ex: 2033 = MQRC_NO_MSG_AVAILABLE)
2. MQMD — o descritor de mensagem
O MQMD é a estrutura que acompanha toda mensagem — contém metadados como tipo de mensagem, prioridade, ID de correlação e formato do payload:
| Campo MQMD | Descrição | Valores comuns |
|---|---|---|
MsgType | Tipo da mensagem | MQMT_DATAGRAM (8), MQMT_REQUEST (1), MQMT_REPLY (2) |
Persistence | Persistência | MQPER_PERSISTENT (1), MQPER_NOT_PERSISTENT (0) |
Priority | Prioridade (0-9) | MQPRI_PRIORITY_AS_Q_DEF (-1) |
MsgId | ID único da mensagem (24 bytes) | Gerado automaticamente pelo MQ |
CorrelId | ID de correlação para respostas | Copia o MsgId do request |
ReplyToQ | Nome da fila de resposta | Nome de uma QLOCAL ou QMODEL |
Format | Formato do payload | MQFMT_STRING ('MQSTR '), MQFMT_NONE |
CodedCharSetId | CCSID do payload | 500 (EBCDIC z/OS), 1208 (UTF-8) |
3. MQCONN e MQOPEN
Em COBOL no z/OS, as chamadas MQ são feitas via CALL para os módulos da API:
* Conectar ao Queue Manager CSQ1
MOVE 'CSQ1' TO WS-QMGR-NAME
CALL 'MQCONN' USING WS-QMGR-NAME
WS-HCONN
WS-COMPCODE
WS-REASON
IF WS-COMPCODE NOT = MQCC-OK
DISPLAY 'MQCONN FAILED: ' WS-REASON
MOVE 8 TO RETURN-CODE
STOP RUN
END-IF
* Abrir fila para escrita
MOVE SPACES TO WS-OBJ-DESC
MOVE MQOD-STRUCID TO MQOD-STRUCID OF WS-OBJ-DESC
MOVE MQOD-VERSION-1 TO MQOD-VERSION OF WS-OBJ-DESC
MOVE 'FILA.PEDIDOS' TO MQOD-OBJNAME OF WS-OBJ-DESC
MOVE MQOT-Q TO MQOD-OBJTYPE OF WS-OBJ-DESC
CALL 'MQOPEN' USING WS-HCONN
WS-OBJ-DESC
MQOO-OUTPUT
WS-HOBJ
WS-COMPCODE
WS-REASON
4. MQPUT — enviando mensagens
* Preparar MQMD
MOVE SPACES TO WS-MSG-DESC
MOVE MQMD-STRUCID TO MQMD-STRUCID OF WS-MSG-DESC
MOVE MQMD-VERSION-2 TO MQMD-VERSION OF WS-MSG-DESC
MOVE MQMT-DATAGRAM TO MQMD-MSGTYPE OF WS-MSG-DESC
MOVE MQPER-PERSISTENT TO MQMD-PERSIST OF WS-MSG-DESC
MOVE MQFMT-STRING TO MQMD-FORMAT OF WS-MSG-DESC
MOVE 500 TO MQMD-CODED-CHAR-SET-ID OF WS-MSG-DESC
* Preparar PMO (Put Message Options)
MOVE SPACES TO WS-PUT-OPT
MOVE MQPMO-STRUCID TO MQPMO-STRUCID OF WS-PUT-OPT
MOVE MQPMO-SYNCPOINT TO MQPMO-OPTIONS OF WS-PUT-OPT
* Payload da mensagem
MOVE 'PEDIDO:0001:PRODUTO:MESA:QTD:002'
TO WS-MSG-BUFFER
MOVE LENGTH OF WS-MSG-BUFFER TO WS-MSG-LEN
CALL 'MQPUT' USING WS-HCONN
WS-HOBJ
WS-MSG-DESC
WS-PUT-OPT
WS-MSG-LEN
WS-MSG-BUFFER
WS-COMPCODE
WS-REASON
💡 MQPMO-SYNCPOINT e controle transacional
MQPMO-SYNCPOINT inclui o PUT na unidade de trabalho do programa — a mensagem só é confirmada quando o MQCMIT (commit) for chamado. Se o programa der ABEND antes do commit, o MQ faz rollback automático e a mensagem não é enviada. Use MQPMO-NO-SYNCPOINT para PUT imediato sem controle transacional.
5. MQGET — recebendo mensagens
* Abrir fila para leitura
MOVE 'FILA.PEDIDOS' TO MQOD-OBJNAME OF WS-OBJ-DESC
CALL 'MQOPEN' USING WS-HCONN WS-OBJ-DESC
MQOO-INPUT-SHARED
WS-HOBJ WS-COMPCODE WS-REASON
* Preparar GMO (Get Message Options)
MOVE SPACES TO WS-GET-OPT
MOVE MQGMO-STRUCID TO MQGMO-STRUCID OF WS-GET-OPT
MOVE MQGMO-VERSION-2 TO MQGMO-VERSION OF WS-GET-OPT
MOVE MQGMO-SYNCPOINT TO MQGMO-OPTIONS OF WS-GET-OPT
* Loop de leitura
PERFORM UNTIL WS-REASON = MQRC-NO-MSG-AVAILABLE
MOVE SPACES TO WS-MSG-BUFFER
MOVE LENGTH OF WS-MSG-BUFFER TO WS-MAX-MSG-LEN
CALL 'MQGET' USING WS-HCONN
WS-HOBJ
WS-MSG-DESC
WS-GET-OPT
WS-MAX-MSG-LEN
WS-MSG-BUFFER
WS-MSG-LEN
WS-COMPCODE
WS-REASON
IF WS-COMPCODE = MQCC-OK
PERFORM PROCESSAR-MENSAGEM
CALL 'MQCMIT' USING WS-HCONN
WS-COMPCODE WS-REASON
END-IF
END-PERFORM
6. Exemplo completo em COBOL
Reason codes MQ mais comuns que toda aplicação deve tratar:
| Reason Code | Constante | Significado |
|---|---|---|
| 0 | MQRC_NONE | Sucesso |
| 2033 | MQRC_NO_MSG_AVAILABLE | Fila vazia — nenhuma mensagem disponível |
| 2035 | MQRC_NOT_AUTHORIZED | Usuário sem permissão para a fila |
| 2058 | MQRC_Q_MGR_NAME_ERROR | Nome do Queue Manager inválido ou não existe |
| 2085 | MQRC_UNKNOWN_OBJECT_NAME | Fila não existe no Queue Manager |
| 2110 | MQRC_FORMAT_ERROR | Formato da mensagem incompatível |
| 2162 | MQRC_Q_FULL | Fila atingiu MAXDEPTH — não aceita mais mensagens |
| 2009 | MQRC_CONNECTION_BROKEN | Conexão com o QM foi perdida |