API-Routinen - Zweck und Verwendung

#### Search Results

Search

# API-Routinen - Zweck und Verwendung

- Zugriff auf Entire Operations aus anderen Anwendungen

- Auffinden und Implementieren einer API

- Regeln und Einschränkungen für die Benutzung von APIs

- Vorhanden API-Routinen testen

- API-spezifische Parameter-Definitionen

## Zugriff auf Entire Operations aus anderen Anwendungen

Sie können eine API benutzen, um aus einer beliebigen Natural-Anwendung heraus Zugriff auf interne Entire Operations-Daten zu ermöglichen.

Eine API stellt Folgendes zur Verfügung:

- Dynamische Verbindung zur Entire Operations-Datei

- Zugriff auf Bedingungen

- Zugriff auf Symbole

- Informationen in das Entire Operations Protokoll schreiben

Eine API kann innerhalb und außerhalb von Entire Operations für verschiedene Aufgaben benutzt werden. Zum Beispiel:

- Symboltabellen während der Ausführung eines Job-Netzwerkes dynamisch ändern.

- Bedingungen aus Natural-Programmen heraus ändern.

- Informationen zwischen Entire Operations und einer beliebigen Online- oder Batch-Anwendung austauschen.

- Eingabebedingungen für Job-Netzwerke von Online-Anwendungen setzen.

- Von Anwendungen den Status von Job-Netzwerken abfragen.

- Entire Operations-Symbole aus externen Tabellen setzen.

- Entire Operations-Symbole zur Benutzung in externen Anwendungen abfragen.

## Auffinden und Implementieren einer API

Die Entire Operations APIs (Anwendungsprogrammierschnittstellen) werden als Natural-Objekte des Typs Subprogramm in der System-Bibliothek SYSEOR ausgeliefert.

Die übliche Namenskonvention für ein API-Subprogramm ist:

    NOPUxxxy

Bedeutung der Namensbestandteile:

`NOPU` | Entire Operations-API-Routine.
`xxx` | Programm-Name (enthält manchmal eine Versionsnummer).
`y` | Programm-Typ:
`N` | Natural-Objekttyp Subprogramm
`P` | Natural-Objekttyp Programm

Um eine Entire Operations API-Routinen zu benutzen:

- Rufen Sie das API-Subprogramm aus einem Natural-Programm auf, das ein Natural-Statement `CALLNAT` ausführt, indem Sie die folgende Syntax benutzen:

      CALLNAT 'NOPUxxxN' parameters

  dabei steht `parameters` für die einzelnen API-Parameter, die an das API-Subprogramm übergeben werden können. Siehe auch API-spezifische Parameter-Definition.

Eine Beschreibung dieses Statements `CALLNAT` ist in der Natural Statements-Dokumentation enthalten.

## Regeln und Einschränkungen für die Benutzung von APIs

Bei der Benutzung einer API gelten folgende generellen Regeln:

- Wir empfehlen, dass Sie keine API-Routinen umbenennen, weil diese auch intern von Entire Operations benutzt werden.

- Die Routinen, die mit der vorhergegangenen Entire Operations-Version ausgeliefert wurden, werden weiterhin unterstützt (außer sie werden speziell abgekündigt, und nur wenn sie erneut in der aktuellen `SYSEOR`-Bibliothek mit ausgeliefert werden). Sie können ihre Aufrufe in eine neuere Version konvertieren, wenn Sie die aufrufenden Programme verändern.

  Ändern Sie alle relevanten `CALLNAT`-Statements und passen Sie die API-Parameterliste entsprechend an. Die volle Bandbreite der Funktionen und deren Funktionalität ist immer nur mit der neuesten API-Version verfügbar.

- Bitte beachten Sie, dass zwischen den Versionswechseln die internen Datenstrukturen von Entire Operations Änderungen unterliegen. Die Verwendung einer veralteten API-Routine kann zur Folge haben, dass inkonsistente Daten auftreten und/oder dass der Entire Operations-Monitor unerwartet ausfällt oder dass Entire Operations abnormal beendet wird.

- Bei neueren API-Versionen können neue Felder hinzugekommen sein. Sie können diese Felder leer lassen oder auf Null setzen, wenn im Deskriptor `(für zukünftige Verwendung)` steht. Diese Felder sollen ihre Bedeutung erst mit einer zukünftigen Version von Entire Operations erhalten.

- Innerhalb von Entire Operations APIs wird kein `END TRANSACTION`-Statement ausgeführt.

- Wenn Sie APIs aus einem Entire Operations User Exit aufrufen, dürfen Sie innerhalb des Exit kein `END TRANSACTION`-Statement codieren. Siehe Codier-Regeln für die User Exits.

- Wenn Sie APIs nicht aus einem Entire Operations User Exit, sondern von einer anderen Stelle aus aufrufen, müssen Sie an einer geeigneten Stelle nach dem `CALLNAT`-Statement ein `END TRANSACTION`-Statement codieren, um die Transaktionslogik von Entire Operations zu schließen.

- Sie können die Parameternamen ändern, jedoch nicht das Parameterformat, die Anzahl und die Reihenfolge.

#### Zugriff auf APIs einschränken

Wenn Natural Security in Ihrer Umgebung installiert ist, können Sie den Natural RPC-Zugriff auf bestimmte APIs einschränken.

Weitere Informationen siehe Option Service Protection des RPC-Server-Profils, die unter Allowing/Disallowing Services in der Natural Security-Dokumentation beschrieben ist.

## Vorhanden API-Routinen testen

Sie können das Natural-Programm `NOPUT1-P` aufrufen, um festzustellen, wie die API-Routinen auf echte Daten reagieren. Es zeigt, wie die Aufrufe der gelieferten Routinen zu codieren und ihre Rückgabe-Codes zu überprüfen sind.

Der Quellcode und das katalogisierte Objekt des Programms `NOPUT1-P` werden in der System-Bibliothek `SYSEOR` ausgeliefert.

Wenn Sie das Programm `NOPUT1-P` ausführen, können Sie die benötigte API-Routine in einem Bildschirm, wie im folgenden Beispiel gezeigt, auswählen und testen.

        Entire Operations - API Routines

    Please Select:
      Network / Job Status       ST                  NOPUST3N
      Conditions                 CO                  NOPUCN3N
      Resource Master            RM                  NOPURS1N
      Resource Usage             RU                  NOPURE2N
      Symbols                    SY                  NOPUSY7N
      Calendars/Schedules        CS                  NOPUCS1N
      Activation                 AC                  NOPUAC5N
      Milestone                  MI                  NOPUMI1N
      Subnetwork                 SN                  NOPUSN2N
      Job Import                 JI                  NOPUJI4N
      Version Info               VE                  NOPUVI2N
      Symbol Prompt Texts        SP                  NOPUSP3N
      Job Schedule               SC                  NOPUJS2N
      Log Monitor Activity       LM                  NOPMLA1N
      Active Job Statistics      AS                  NOPUAS1N
      Message Text               MT                  NOPUMT3N
                            ===> __  (blank or . or PF3  ==>  End)

## API-spezifische Parameter-Definitionen

Die Parameter, die mit einem `CALLNAT`-Statement an ein API-Subprogramm übergeben werden können, sind im Abschnitt Liste der verfügbaren Entire Operations API-Routinen für jede API beschrieben.

Die Datentypen, die in den Listen mit Parameterbeschreibungen einer API aufgeführt sind, entsprechen dem Natural-Format und der Länge von Benutzervariablen, z.B. A1 für eine alphanumerische Variable mit einer Länge von einem Byte. Ausführliche Informationen siehe Abschnitt Benutzervariablen im Natural-Leitfaden zur Programmierung.

Standardmäßig erfolgt die Übergabe von Parametern an ein API-Subprogramm durch Referenzierung seiner Adresse ("By Reference") an ein Subprogramm übergeben, d.h. die Datenübergabe erfolgt mittels Adressparametern, wobei die Parameterwerte selbst nicht bewegt werden. Die Parameterbeschreibungen geben Parameter an, die mit `BY VALUE`, `BY VALUE RESULT` und/oder `OPTIONAL` definiert werden.

> OPTIONAL

>   Bei einem mit `OPTIONAL` definierten Parameter kann wahlweise ein Wert vom aufrufenden Objekt an diesen Parameter übergeben werden.

>   Da die Reihenfolge der Parameter fest ist, muss für gewöhnlich ein Wert vom aufrufenden Programm an jeden einzelnen Parameter übergeben werden. Ein mit `OPTIONAL` definierter Parameter kann jedoch übersprungen werden, indem er im `CALLNAT`-Statement durch `1X` ersetzt wird. Siehe Beispiel für die Benutzung von NOPUST3N.

>   Weitere Informationen zu `OPTIONAL`-Parametern siehe `DEFINE DATA`-Statement, Definition von Parameterdaten, Syntax-Element-Beschreibung, `OPTIONAL`, in der Natural-Statements-Dokumentation.

> BY VALUE

>   Mit `BY VALUE` wird ein Parameter direkt als Wert ("By Value") an ein API-Subprogramm übergeben, d.h. statt der Adresse des Parameters wird der tatsächliche Parameterwert selbst übergeben. Das bedeutet, das Feld in dem Subprogramm braucht nicht dasselbe Format und dieselbe Länge zu haben wie der im `CALLNAT`-Statement übergebene Parameter.

> BY VALUE RESULT

>   Ein mit `BY VALUE RESULT` definierter Parameter wird in beiden Richtungen als Wert ("By Value") übergeben, d.h. der tatsächliche Parameterwert wird vom aufrufenden Programm an das API-Subprogramm übergeben und bei der Rückkehr zum aufrufenden Programm wird der tatsächliche Parameterwert von dem Subprogramm an das aufrufende Programm zurückgegeben.

Weitere Informationen siehe Definition von Parameter Data im Abschnitt DEFINE DATA der Natural Statements-Dokumentation.

### On this page

- Zugriff auf Entire Operations aus anderen Anwendungen
- Auffinden und Implementieren einer API
- Regeln und Einschränkungen für die Benutzung von APIs
- Vorhanden API-Routinen testen
- API-spezifische Parameter-Definitionen