API-Routinen - Zweck und Verwendung

• Besondere Merkmale der Entire Operations-APIs

• Auffinden und Implementieren einer API

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

• Vorhanden API-Routinen testen

• API-spezifische Parameter-Definitionen

Besondere Merkmale der Entire Operations-APIs

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:

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.

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.