API-Routinen benutzen

Die Entire Operations APIs werden als Natural-Objekte des Typs Subprogram innerhalb der Entire Operations-Bibliothek geliefert.

Die Namenskonvention ist:

NOPUxxxy

Bedeutung der Namensbestandteile:

NOPU Die Entire Operations-API-Routine.
xxx Der Programm-Name (enthält manchmal eine Versionsnummer).
y Der Programm-Typ:
N Natural-Objekttyp Subprogram
P Natural-Objekttyp Program

Um die Entire Operations API-Routinen zu nutzen, müssen Sie zumindest die Bibliotheken SYSEOR und SYSSAT als Steplib deklarieren.

Um ein API-Subprogramm auszuführen, benutzen Sie das Natural-Statement CALLNAT. Eine Beschreibung dieses Statements ist in der Natural Statements-Dokumentation enthalten.

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

Durch das Setzen der erforderlichen Entire Operations-Benutzerprivilegien in der entsprechenden Entire Operations-Administrationsfunktion können Sie die Benutzung eines API erlauben oder nicht erlauben. Darüber hinaus können Sie den Natural RPC-Zugriff auf bestimmte APIs einschränken, wenn Natural Security installiert ist. Weitere Informationen siehe Option Service Protection eines RPC-Servers, die unter Allowing/Disallowing Services in der Natural Security-Dokumentation beschrieben ist.

Bei der Benutzung einer API gelten folgende generellen Regeln:

  • Sie können 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 das aufrufende Programm verändern.

    Zum Beispiel, ab Entire Operations Version 5.3.1, müssen Sie anstatt dem vorher gültigen Programm NOPUAC4N das Netzwerk-Aktivierungs-API NOPUAC5N benutzen. Ändern Sie alle CALLNAT NOPUAC4N-Aufrufe in CALLNAT NOPUAC5N und passen Sie die API-Parameterliste entsprechend an. Die komplette Bandbreite der Funktionen und deren Funktionalität ist immer nur mit der neuesten API-Version verfügbar.

  • Es ist strikt untersagt, API-Routinen zu benutzen, die mit einer früheren Version von Entire Operations ausgeliefert wurden, selbst dann wenn Namensgleichheit besteht. 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 nicht korrekt funktioniert oder 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 "for future use" (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-Regelen für User Exits.

  • Wenn Sie APIs nicht aus einem Entire Operations User Exit, sondern von einer anderen Stelle aus aufrufen, gilt Folgendes:

    Sie müssen 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.

  • Parameter, die mit dem Kommentar "for future use" (für zukünftige Verwendung) versehen sind, müssen auf jeden Fall angegeben werden. Es genügt, leere Parameter zu benutzen. Bitte beachten Sie, dass solche Parameter in späteren Versionen von Entire Operations eine Bedeutung erhalten können.

API-Routinen aufrufen

Zuerst muss die Benutzer-Anwendung eine Verbindung zu den Entire Operations-Systemdateien aufbauen. Dies kann folgendermaßen geschehen:

Wenn der Aufruf der Benutzer-Anwendung erweitert ist mit entweder

NTLFILE ID=216,DBID=eor-sysf1-dbid,FNR=eor-sysf1-fnr
NTLFILE ID=131,DBID=sat-log-dbid,FNR=sat-log-fnr (in parameter module)

oder

LFILE (216,eor-sysf1-dbid,eor-sysf1-fnr)
LFILE (131,sat-log-dbid,sat-log-fnr)     (as dynamic parameter)

dann ist die Verbindung bereits aufgebaut.

Beispiel für die Verwendung von API-Routinen

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                  NOPUSY6N     
  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)