Natural Messaging ist eine Softwarekomponente, die eine nahtlose
Interaktion zwischen Natural-Anwendungen und IBM MQ-Systemen ermöglicht. Sie
unterstützt nachrichtenorientierte Middleware-Operationen (PUT,
GET und BROWSE) direkt aus Natural-Programmen heraus,
sodass keine Low-Level-MQ-APIs mehr erforderlich sind.
Diese Funktionalität wird durch strukturierte Datensichten (Views) bereitgestellt, die die erforderlichen Felder und Parameter für MQ-Operationen definieren. Auf diese Datensichten kann mit der Standard-Natural-Syntax zugegriffen werden, sodass sich Messaging-Operationen nahtlos in die Programmierumgebung integrieren lassen.
Hauptmerkmale:
PUT: Einstellen von Nachrichten in
Warteschlangen.
GET: Abrufen von Nachrichten aus
Warteschlangen.
BROWSE: Lesen von Nachrichten, ohne sie aus den
Warteschlangen zu löschen.
Der Zugriff auf Natural Messaging-Datensichten erfolgt unter Verwendung der folgenden Natural-Statements:
PROCESS zum Ausführen von
Aktionen wie PUT oder GET.
FIND zum
Durchsuchen von Nachrichten (nur Lesezugriff).
Das jeweils verwendete Statement hängt von der Operation ab.
Das PROCESS-Statement wird
verwendet, um MQ-Operationen wie PUT und GET
auszuführen, wobei die spezifische Operation durch das Feld
FUNCTION bestimmt wird.
Allgemeine Syntax:
PROCESS MQ-QUEUE-VIEW USING
FUNCTION = 'PUT' | 'GET',
QMANAGER = queue-manager-name,
QNAME = queue-name,
[optional control or message fields = value]
[optional GIVING field-name]
Setzen Sie FUNCTION = 'PUT'.
Geben Sie den Namen der Zielwarteschlange und des Warteschlangenmanagers ein.
Füllen Sie je nach Größe der Nutzlast (Payload) eines der
Felder für den Nachrichteninhalt aus (MESSAGE,
MESSAGE-10K usw.).
Optional können Sie Folgendes festlegen:
Nachrichtenattribute wie PERSISTENCE,
EXPIRY und MESSAGE-TYPE.
Nachrichtenkennungen wie MESSAGE-ID und
CORRELATION-ID.
Bei Bedarf zusätzliche MQ-PUT-Optionen.
Anmerkungen:
PUT-Operation ausführen, müssen
Sie sich vergewissern, dass das Feld DATA-LENGTH auf die
tatsächliche MESSAGE-Größe eingestellt ist. So wird
sichergestellt, dass nur der relevante Teil des Nachrichtenfeldes übertragen
wird, auch wenn das Feld größere Nachrichten aufnehmen kann.
DATA-LENGTH nicht eingestellt
ist, wird die Länge von MESSAGE berechnet, indem die
nachgestellten Leerzeichen für das Alpha-Feld (x'40'), die nachgestellten
Leerzeichen für das Unicode-Feld (x'0020') und das nachgestellte x'00' für das
Binärfeld entfernt werden.
Setzen Sie FUNCTION = 'GET'.
Geben Sie den Namen der Zielwarteschlange und des Warteschlangenmanagers ein.
Optional können Sie Filter anhand von MESSAGE-ID,
CORRELATION-ID oder anderen Auswahlkriterien anwenden.
Legen Sie die relevanten MQ-GET-Optionen fest, z.
B. WAIT-INTERVAL und TRUNCATE.
Der Inhalt der abgerufenen Nachricht und die zugehörigen
Nachrichteneigenschaften werden in den im Datendefinitionsmodul
MQ-QUEUE definierten Feldern zurückgegeben.
Überprüfen Sie nach einer GET-Operation das Feld
DATA-LENGTH, um die tatsächliche Größe der abgerufenen Nachricht
zu ermitteln.
Anmerkungen:
PUT- oder
GET-Operation immer die Felder ERROR-CODE und
ERROR-TEXT, um die erfolgreiche Ausführung zu verifizieren oder
etwaige Probleme zu erkennen. Wenn diese Felder verwendet werden, werden
MQ-bezogene Fehler nicht als Natural-Laufzeitfehler ausgegeben. Stattdessen
werden sie unterdrückt, und der entsprechende MQ-Ursachencode und seine
Beschreibung werden in den Feldern ERROR-CODE bzw.
ERROR-TEXT angegeben.
PUT-Operation wird das
Feld DATA-LENGTH auf die tatsächliche MESSAGE-Größe
gesetzt. Wenn die Nachricht gekürzt wird, gibt das Feld
DATA-LENGTH die Größe der gekürzten Nachricht an.
Das FIND-Statement wird verwendet, um
MQ-Nachrichten zu durchsuchen, ohne sie aus der Warteschlange zu entfernen. Das
Durchsuchen ist das Standardverhalten, daher ist keine Zuweisung per
FUNCTION erforderlich.
Allgemeine Syntax:
FIND MQ-QUEUE-VIEW WITH
QMANAGER = queue-manager-name AND
QNAME = queue-name AND
[optional control or message filter fields = value]
Unterstützt die Nachrichtenfilterung mittels Deskriptoren wie
MESSAGE-ID und CORRELATION-ID, wodurch das Abrufen
von Nachrichten anhand spezifischer Kriterien ermöglicht wird.
Nachrichten werden nicht "konsumiert", was bedeutet, dass sie nach dem Vorgang in der Warteschlange erhalten bleiben.
In Natural Messaging gelten die Systemvariablen
*NUMBER und *ISN
nicht im Zusammenhang mit den Statements FIND und
PROCESS.
Die folgenden Beispielprogramme finden Sie in der Bibliothek
SYSEXNMQ.
** Example 'GETIBMMQ': Get MQ message from IBM-MQ queue.
************************************************************************
DEFINE DATA LOCAL
1 MQ-QUEUE-VIEW VIEW OF MQ-QUEUE
2 ERROR-CODE /* MQ reason code
2 ERROR-TEXT /* Text describing the reason code
2 FUNCTION /* Operation: GET, PUT
2 QMANAGER /* Queue manager name
2 QNAME /* Queue name
2 PRIORITY /* Priority (0=low, 9=high)
2 MESSAGE-10K /* Extended message field
2 PUT-DATE /* Put date (YYYYMMDD)
2 PUT-TIME /* Put time (HHMMSSTH)
2 REPLY-TO-QNAME /* Queue name for receiving reply
2 REPLY-TO-QMANAGER /* Queue manager to receive reply
2 USER-ID /* User ID of PUT/GET requester
*
1 I (I4) /* Count number of messages read
1 I-MAX (I4) INIT <10> /* Default number of messages to be read
1 Q-MANAGER (A48)
1 Q-NAME (A48)
END-DEFINE
*
* The GET function is used to retrieve messages from the queue. Once a
* message is retrieved, it is removed from the queue.
*
SET KEY ALL
INPUT (AD=MITL'_' IP=OFF ZP=ON SG=OFF CD=TU)
'GET information from Natural Messaging Queue' (I) /
'--------------------------------------------' (I) //
'Queue name ..................' Q-NAME /
'Queue manager name ..........' Q-MANAGER /
'Maximum number of messages ..' I-MAX (AD=M) ///
'NOTE: Once a message is retrieved, it is removed from the queue.' ///
'Press ENTER to continue or any PF-key to stop.'
*
IF *PF-KEY NE 'ENTR'
ESCAPE ROUTINE
END-IF
*
FOR I = 1 TO I-MAX
*
* Perform function GET to retrieve information from the queue
*
PROCESS MQ-QUEUE-VIEW USING
MQ-QUEUE-VIEW.FUNCTION = 'GET', /* Function name : GET/PUT
MQ-QUEUE-VIEW.QMANAGER = Q-MANAGER, /* QUEUE manager name
MQ-QUEUE-VIEW.QNAME = Q-NAME /* QUEUE Name
*
PRINT 'Message count : ' I (AD=L)
PRINT 'Message : ' MQ-QUEUE-VIEW.MESSAGE-10K
PRINT 'Queue manager : ' MQ-QUEUE-VIEW.QMANAGER
PRINT 'Queue name : ' MQ-QUEUE-VIEW.QNAME
PRINT 'Priority : ' MQ-QUEUE-VIEW.PRIORITY (AD=L)
PRINT 'Put date : ' MQ-QUEUE-VIEW.PUT-DATE
PRINT 'Put time : ' MQ-QUEUE-VIEW.PUT-TIME
PRINT 'User ID : ' MQ-QUEUE-VIEW.USER-ID
PRINT 'Reply queue manager : ' MQ-QUEUE-VIEW.REPLY-TO-QMANAGER
PRINT 'Reply queue name : ' MQ-QUEUE-VIEW.REPLY-TO-QNAME
PRINT '*'(70)(I)
*
* Check for error
*
IF ERROR-CODE NE 0
PRINT / 'Error occurred while performing the GET function.' /
PRINT 'Error code : ' ERROR-CODE (AD=L)
PRINT 'Error text : ' ERROR-TEXT
PRINT '*'(70)(I)
ESCAPE BOTTOM /* Stop processing if error occurs
END-IF
*
END-FOR
END
** Example 'PUTIBMMQ': Put message to IBM-MQ queue.
************************************************************************
DEFINE DATA LOCAL
1 MQ-QUEUE-VIEW VIEW OF MQ-QUEUE
2 ERROR-CODE /* MQ reason code
2 ERROR-TEXT /* Text describing the reason code
2 FUNCTION /* Operation: GET, PUT
2 QMANAGER /* Queue manager name
2 QNAME /* Queue name
2 PRIORITY /* Priority (0=low, 9=high)
2 MESSAGE-10K /* Extended message field
2 PUT-DATE /* Put date (YYYYMMDD)
2 PUT-TIME /* Put time (HHMMSSTH)
2 REPLY-TO-QNAME /* Queue name for receiving reply
2 REPLY-TO-QMANAGER /* Queue manager to receive reply
2 USER-ID /* User ID of PUT/GET requester
*
1 EMPLOY-VIEW VIEW OF EMPLOYEES
2 NAME
*
1 DATE-A (A8)
1 TIME-A (A8)
1 USER1 (A8)
1 Q-MANAGER (A48)
1 Q-NAME (A48)
END-DEFINE
*
* The PUT function is used to send (or write) a message to a queue.
* The message remains in the queue until it is either retrieved
* (using GET) or expires whichever occurs first.
*
SET KEY ALL
INPUT (AD=MITL'_' IP=OFF ZP=ON SG=OFF CD=TU)
'PUT information on Natural Messaging Queue' (I) /
'------------------------------------------' (I) //
'Queue name ..............' Q-NAME /
'Queue manager name ......' Q-MANAGER ///
'Press ENTER to continue or any PF-key to stop.'
/*
IF *PF-KEY NE 'ENTR'
ESCAPE ROUTINE
END-IF
*
* In the example below, EMPLOYEE-VIEW data will be written in MQ-QUEUE
*
READ EMPLOY-VIEW BY ISN STARTING FROM 1 ENDING AT 10
*
* Move current time, date and user to the queue
*
MOVE EDITED *TIMX (EM=HHIISST'0') TO TIME-A
MOVE *DATN TO DATE-A
MOVE *USER TO USER1
*
* Move name of the employee to the queue
*
MOVE NAME TO MQ-QUEUE-VIEW.MESSAGE-10K
*
* Perform function PUT to write data into the queue
*
PROCESS MQ-QUEUE-VIEW USING
MQ-QUEUE-VIEW.FUNCTION = 'PUT',
MQ-QUEUE-VIEW.QMANAGER = Q-MANAGER,
MQ-QUEUE-VIEW.QNAME = Q-NAME,
MQ-QUEUE-VIEW.PRIORITY = 1,
MQ-QUEUE-VIEW.PUT-DATE = DATE-A,
MQ-QUEUE-VIEW.PUT-TIME = TIME-A,
MQ-QUEUE-VIEW.REPLY-TO-QMANAGER = Q-MANAGER,
MQ-QUEUE-VIEW.REPLY-TO-QNAME = Q-NAME,
MQ-QUEUE-VIEW.USER-ID = USER1
*
PRINT 'Message count : ' *COUNTER (AD=L)
PRINT 'Message : ' MQ-QUEUE-VIEW.MESSAGE-10K
PRINT 'Queue manager : ' MQ-QUEUE-VIEW.QMANAGER
PRINT 'Queue name : ' MQ-QUEUE-VIEW.QNAME
PRINT 'Priority : ' MQ-QUEUE-VIEW.PRIORITY (AD=L)
PRINT 'Put date : ' MQ-QUEUE-VIEW.PUT-DATE
PRINT 'Put time : ' MQ-QUEUE-VIEW.PUT-TIME
PRINT 'User ID : ' MQ-QUEUE-VIEW.USER-ID
PRINT 'Reply queue manager : ' MQ-QUEUE-VIEW.REPLY-TO-QMANAGER
PRINT 'Reply queue name : ' MQ-QUEUE-VIEW.REPLY-TO-QNAME
PRINT '*'(70)(I)
*
* Check for error
*
IF ERROR-CODE NE 0
PRINT / 'Error occurred while performing the PUT function.' /
PRINT 'Error code : ' ERROR-CODE (AD=L)
PRINT 'Error text : ' ERROR-TEXT
PRINT '*'(70)(I)
ESCAPE BOTTOM /* Stop processing if error occurs
END-IF
*
END-READ
*
END
** Example 'BRWIBMMQ': Browse MQ messages.
************************************************************************
DEFINE DATA LOCAL
1 MQ-QUEUE-VIEW VIEW OF MQ-QUEUE
2 ERROR-CODE /* MQ reason code
2 ERROR-TEXT /* Text describing the reason code
2 FUNCTION /* Operation: GET, PUT
2 QMANAGER /* Queue manager name
2 QNAME /* Queue name
2 PRIORITY /* Priority (0=low, 9=high)
2 MESSAGE-10K /* Extended message field
2 PUT-DATE /* Put date (YYYYMMDD)
2 PUT-TIME /* Put time (HHMMSSTH)
2 REPLY-TO-QNAME /* Queue name for receiving reply
2 REPLY-TO-QMANAGER /* Queue manager to receive reply
2 USER-ID /* User ID of PUT/GET requester
*
1 I-MAX (I4) INIT <10> /* Default number of messages to be read
1 Q-MANAGER (A48)
1 Q-NAME (A48)
END-DEFINE
*
* The browse function lets you inspect the messages in the queue
* without removing them.
*
SET KEY ALL
INPUT (AD=MITL'_' IP=OFF ZP=ON SG=OFF CD=TU)
'Browse Natural Messaging Queue' (I) /
'------------------------------' (I) //
'Queue name ..................' Q-NAME /
'Queue manager name ..........' Q-MANAGER /
'Maximum number of messages ..' I-MAX (AD=M) ///
'Press ENTER to continue or any PF-key to stop.'
/*
*
IF *PF-KEY NE 'ENTR'
ESCAPE ROUTINE
END-IF
*
FIND (I-MAX) MQ-QUEUE-VIEW WITH
MQ-QUEUE-VIEW.QMANAGER = Q-MANAGER AND /* Name of Queue Manager
MQ-QUEUE-VIEW.QNAME = Q-NAME /* Name of the Queue
*
PRINT 'Message count : ' *COUNTER (AD=L)
PRINT 'Message : ' MQ-QUEUE-VIEW.MESSAGE-10K
PRINT 'Queue manager : ' MQ-QUEUE-VIEW.QMANAGER
PRINT 'Queue name : ' MQ-QUEUE-VIEW.QNAME
PRINT 'Priority : ' MQ-QUEUE-VIEW.PRIORITY (AD=L)
PRINT 'Put date : ' MQ-QUEUE-VIEW.PUT-DATE
PRINT 'Put time : ' MQ-QUEUE-VIEW.PUT-TIME
PRINT 'User ID : ' MQ-QUEUE-VIEW.USER-ID
PRINT 'Reply queue manager : ' MQ-QUEUE-VIEW.REPLY-TO-QMANAGER
PRINT 'Reply queue name : ' MQ-QUEUE-VIEW.REPLY-TO-QNAME
PRINT '*'(70)(I)
*
* Check for error
*
IF ERROR-CODE NE 0
PRINT / 'Error occurred while performing the browse function.' /
PRINT 'Error code : ' ERROR-CODE (AD=L)
PRINT 'Error text : ' ERROR-TEXT
PRINT '*'(70)(I)
ESCAPE BOTTOM /* Stop processing if error occurs
END-IF
*
END-FIND
*
END
Die Datensichtbeschreibung enthält die folgenden Informationen zu den in der View definierten Feldern:
| Eintrag | Bedeutung | |
|---|---|---|
| Field Name | Der Name des Feldes, wie er in Natural verwendet wird. | |
| F/L | Feldformat und -länge: | |
| A | Alphanumerisch. | |
| B | Binär. | |
| I | Ganzzahl. | |
| DE | Deskriptor.
Ein |
|
| Description | Kurze Erläuterung des Zwecks oder der Funktion des Feldes. | |
| Operation | Anwendbare MQ-Operationen
(GET, PUT, BROWSE), bei denen das Feld
relevant ist.
|
|
| Remark | Zusätzliche Einzelheiten, Einschränkungen oder Hinweise zur Verwendung des Feldes. | |
Wird verwendet zum Senden (PUT), Abrufen
(GET) und Lesen (BROWSE) von MQ-Nachrichten mittels
der Statements PROCESS und FIND.
Beschreibung der View-Felder:
| Field Name | F/L | DE | Description | Operation | Remarks |
|---|---|---|---|---|---|
ERROR-CODE
|
I/4 | Zurückgegebener MQ-Ursachencode. | GET, PUT,
BROWSE
|
Überprüfen nach PROCESS und
FIND.
|
|
ERROR-TEXT |
A/58 | Beschreibender Text zum Ursachencode. | GET, PUT,
BROWSE |
||
FUNCTION
|
A/8 | D | Auszuführende Operation: GET oder
PUT.
|
GET, PUT |
Nicht erforderlich bei BROWSE.
|
QMANAGER
|
A/48 | D | Name des Warteschlangen-Managers. | GET, PUT,
BROWSE |
Wird in einer CICS-Umgebung ignoriert. |
QNAME
|
A/48 | D | Name der Warteschlange. | GET, PUT,
BROWSE |
|
MESSAGE-TYPE |
A/8 | D | Nachrichtentyp (Datagramm, Anfrage, Antwort, Bericht). | PUT |
Standardeinstellung: Datagramm |
PRIORITY |
I/4 | D | Priorität der Nachricht (0=niedrig,
9=hoch).
|
PUT |
|
PERSISTENCE |
A/1 | D | Y/N/D-Flag für die Persistenz der Nachricht. | PUT |
Standardeinstellung: D (abhängig von der Warteschlangendefinition) |
PUT-DATE |
A/8 | D | Datum der Einstelloperation (YYYYMMDD). | PUT |
Wird von MQ bei PUT gesetzt.
|
PUT-TIME |
A/8 | D | Zeitepunkt der Einstelloperation (HHMMSSTH). | PUT |
Wird von MQ bei PUT gesetzt.
|
EXPIRY |
I/4 | D | Verfallszeit in 1/10 Sekunden. | PUT |
|
REPLY-TO_QMANAGER |
A/48 | D | Warteschlangen-Manager für Empfang der Antwort. | PUT |
|
REPLY-TO-QNAME |
A/48 | D | Warteschlangenname für Empfang der Antwort. | PUT |
|
BACKOUT-COUNT |
I/4 | D | Anzahl der Backouts der Nachricht. | GET, BROWSE |
|
MESSAGE-ID |
B/24 | D | Nachrichtenkennung. | GET, PUT,
BROWSE |
Wird für die Nachrichtenauswahl verwendet. |
CORRELATION-ID |
B/24 | D | Korrelationskennung. | GET, PUT,
BROWSE |
Wird beim Abgleich von Anfragen und Antworten verwendet. |
USER-ID |
A/12 | D | Benutzerkennung des
PUT/GET-Anforderers.
|
GET, PUT |
|
WAIT-INTERVAL |
I/4 | D | Wartezeit für GET (Millisekunden).
|
GET |
Wird für synchrones GET
verwendet.
|
TRUNCATE |
A/1 | D | Y/N-Flag ob Kürzung erlaubt ist. | GET |
Standardeinstellung: N |
DATA-LENGTH |
I/4 | D | Gesamtlänge der Nachrichtendaten. | PUT |
Setzen vor PUT.
|
FORMAT |
A/8 | D | Nachrichtenformat. | PUT |
|
CCSID |
I/4 | D | Zeichensatzkennung. | PUT |
|
ENCODING |
I/4 | D | Numerisches Kodierungsformat. | PUT |
|
MESSAGE |
A/253 | Standardnachrichtenfeld. | PUT |
Wird für kleinere Nachrichten verwendet. | |
MESSAGE-10K |
A/10240 | Erweitertes Nachrichtenfeld bis zu 10KB. | PUT |
||
MESSAGE-100K |
A/102400 | Erweitertes Nachrichtenfeld bis zu 100KB. | PUT |
||
MESSAGE-1000K |
A/1024000 | Erweitertes Nachrichtenfeld bis zu 1MB. | PUT |
Anmerkungen:
PROCESS- oder FIND-Statement gesetzt sind, werden die
Standardwerte von IBM MQ angewendet.