Natural-Statements und Datensicht (Natural View) für Natural Messaging

#### Search Results

Search

# Natural-Statements und Datensicht (Natural View) für Natural Messaging

- Einführung

- Zugriff auf Natural Messaging in Natural-Programmen

- Beschreibung der Datensicht (View)

## Einführung

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.

## Zugriff auf Natural Messaging in Natural-Programmen

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.

- PROCESS-Statement

- FIND-Statement

- Systemvariablen

- Beispiele

### PROCESS-Statement

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]

#### PUT-Operationen

- 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:

1. Bevor Sie eine `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.
2. Wenn das Feld `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.

#### GET-Operationen

- 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:

1. Überprüfen Sie nach einer `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.
2. Nach dem Ausführen einer `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.

### FIND-Statement

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.

### Systemvariablen

In Natural Messaging gelten die Systemvariablen `*NUMBER` und `*ISN` nicht im Zusammenhang mit den Statements `FIND` und `PROCESS`.

### Beispiele

Die folgenden Beispielprogramme finden Sie in der Bibliothek `SYSEXNMQ`.

- Beispiel 1: Beispiel für ein Natural-Programm zum löschenden Abrufen von Nachrichten aus einer IBM MQ-Warteschlange
- Beispiel 2: Beispiel für ein Natural-Programm zum Einstellen einer Nachricht in eine IBM MQ-Warteschlange
- Beispiel 3: Beispiel für ein Natural-Programm zum nicht-löschenden Lesen von Nachrichten in einer IBM MQ-Warteschlange

#### Beispiel 1: Beispiel für ein Natural-Programm zum löschenden Abrufen von Nachrichten aus einer IBM MQ-Warteschlange

    ** 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

#### Beispiel 2: Beispiel für ein Natural-Programm zum Einstellen einer Nachricht in eine IBM MQ-Warteschlange

    ** 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

#### Beispiel 3: Beispiel für ein Natural-Programm zum nicht-löschenden Lesen von Nachrichten in einer IBM MQ-Warteschlange

    ** 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

## Beschreibung der Datensicht (View)

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 `D` in dieser Spalte bedeutet, dass das Feld in der `WITH`-Klausel eines `FIND`-Statement oder in der `USING`-Klausel eines `PROCESS`-Statement verwendet werden kann.
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.

### View-Name: MQ-QUEUE

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:

1. Es empfiehlt sich, pro View, die für den Zugriff auf MQ verwendet wird, jeweils nur ein einziges Nachrichtenfeld zu definieren.
2. Bei View-Feldern, die nicht explizit im `PROCESS`- oder `FIND`-Statement gesetzt sind, werden die Standardwerte von IBM MQ angewendet.

### On this page

- Einführung
- Zugriff auf Natural Messaging in Natural-Programmen
- Beschreibung der Datensicht (View)