SYSEXT Utility

Mit dem Dienstprogramm ("Utility") SYSEXT können Sie Natural-Anwendungsprogrammierschnittstellen (Application Programming Interfaces/APIs), die in der aktuellen System-Library SYSEXT enthalten sind, finden und testen.

Eine Natural API ist ein Natural-Subprogramm (katalogisiertes Objekt), das dazu benutzt wird, auf Daten zuzugreifen, eventuell Daten zu ändern oder Dienste auszuführen, die für Natural-Statements nicht zugänglich sind. Natural APIs beziehen sich auf Natural, eine Unterkomponente oder ein Unterprodukt.

Folgende Themen werden behandelt:

• Einleitung zu SYSEXT

• SYSEXT Utility aufrufen und beenden

• SYSEXT Utility benutzen

• Interface-Versionen

• Reservierte Schlüsselwörter

• Eine Natural API verwenden

Verwandte Themen:

• Application Programming Interfaces - Natural Security documentation

• Application Programming Interfaces - Natural SAF Security documentation

• APIs, die von Natural Add-on-Produkten zur Verfügung gestellt werden, siehe Dienstprogramm ("Utility") SYSAPI.

Einleitung zu SYSEXT

Die SYSEXT Utility bietet zu jeder Natural API eine Funktionsbeschreibung, ein Beispiel-Programm und API-spezifische Schlüsselwörter.

Hauptmerkmale der SYSEXT Utility sind:

• API-Objekte

  • API-Subprogramm

  • Beispiel-Programm zum Testen

  • Text-Objekt mit Funktionsbeschreibung und Interface-Versionen

• Funktionen

  • APIS auflisten mit Beschreibung, Kategorie und Produktcode

  • Mehrfachauswahl zur API-Abfrage

  • Suche nach Schlüsselwort und Kategorie

  • Umschalten zwischen Anzeigemodi

  • Objekt-Operationen

Bei Natural APIs verfügbare Objekte

Im folgenden Abschnitt werden die Natural-Objekttypen aufgeführt, die zu jeder Natural API typischerweise vorhanden sind. Zusätzliche Objekte, die zu einer bestimmten API verfügbar sein können, werden an dieser Stelle nicht behandelt.

Alle Objekte, die einen Bezug zur API haben, sind in der Library SYSEXT in der Systemdatei FNAT enthalten.

In der folgenden Tabelle steht nnnn für die vierstellige Nummer, durch die die API sowie das entsprechende Beispiel-Programm und Text-Objekt identifizierbar sind.

Bei einigen APIs stehen Copycodes zur Verfügung, die Funktionen bieten, die in Beziehung zur API stehen. Die Copycodes haben den Namen USRnnnnX, wobei X ein Identifizierungszeichen ist (z.B. "Z", "Y" usw.).

SYSEXT Utility aufrufen und beenden

Die SYSEXT Utility können Sie mit folgendem Systemkommando und den im Syntax-Diagramm gezeigten Parametern aufrufen:

Die Parameter, die Sie mit dem Systemkommando angeben können, werden in der folgenden Tabelle beschrieben:

Um die SYSEXT Utility aufzurufen:

• Geben Sie folgendes Systemkommando ein:

  SYSEXT

  Es erscheint ein Menü mit einer Liste aller vorhandenen Natural APIs gemäß den Angaben im ersten Menü (Beispiel):

  07:43:19 ***** NATURAL SYSEXT UTILITY ***** 2010-09-15 User SAG - Menu - Library SYSEXT Cmd Interface Description Prod --- USR*____ _____________________________________________________________ *__ _ USR0010N Get SYSPROF information NAT _ USR0011N Get information on logical file NAT _ USR0020N Read any error message from FNAT or FUSER NAT _ USR0040N Get type of last error NAT _ USR0050N Get SYSPROD information NAT _ USR0060N Copy LFILE definition from FNAT to FUSER NAT _ USR0070P Define editor default profile 'SYSTEM' NAT _ USR0080N Get or set type and name of editor contents NAT _ USR0100N Maintain record length of VSAM datasets NVS _ USR0120N Read Natural short error message NAT _ USR0210N Save, catalog or stow Natural object NAT _ USR0220N Read Natural long error message NAT _ USR0320N Read user short error message from FNAT or FUSER NAT Category .. ______________________________ Keyword .. ____________________ Command ===> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Reset Exit Desc Curr -- - + ++ > Canc

Sie können die SYSEXT Utility mit beliebigen Parametern (s.o.) aufrufen, z.B. um das zweite Menü direkt beim Start der Utility anzuzeigen:

SYSEXT SECOND

Folgendes Menü wird angezeigt (Beispiel):

 07:43:19              ***** NATURAL SYSEXT UTILITY *****             2010-09-15
 User SAG                            - Menu -                   Library SYSEXT

 Cmd Interface Description                        Category
 --- USR*____  __________________________________ *_____________________________
  _  USR0010N  Get SYSPROF information            SYSTEM COMMANDS
  _  USR0011N  Get information on logical file    SYSTEM FILES
  _  USR0020N  Read any error message from FNAT o ERROR MESSAGES
  _  USR0040N  Get type of last error             ERROR HANDLING
  _  USR0050N  Get SYSPROD information            SYSTEM COMMANDS
  _  USR0060N  Copy LFILE definition from FNAT to SYSTEM FILES
  _  USR0070P  Define editor default profile 'SYS EDITOR
  _  USR0080N  Get or set type and name of editor EDITOR
  _  USR0100N  Maintain record length of VSAM dat VSAM
  _  USR0120N  Read Natural short error message   ERROR MESSAGES
  _  USR0210N  Save, catalog or stow Natural obje NATURAL OBJECTS
  _  USR0220N  Read Natural long error message    ERROR MESSAGES
  _  USR0320N  Read user short error message from ERROR MESSAGES

  Category .. ______________________________  Keyword .. ____________________

 Command ===>
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Reset Exit  Desc  Curr  --    -     +     ++    <           Canc   

Alternativ können Sie die SYSEXT Utility ohne Parameter aufrufen und dann PF-Tasten benutzen, um das angezeigte Menü wunschgemäß anzupassen. Siehe PF-Tasten.

Um die SYSEXT Utility zu beenden:

• Drücken Sie im Menü der SYSEXT Utility PF3 oder PF12.

  Oder:
  Geben Sie in der Kommandozeile einen Punkt (.) oder EXIT ein.

SYSEXT Utility benutzen

Folgende Themen werden behandelt:

• Bestandteile des SYSEXT Utility-Menüs

• PF-Tasten

• Zeilenkommandos

• Utility-Kommandos

Bestandteile des SYSEXT Utility-Menüs

Das SYSEXT Utility-Menü enthält eine Liste der APIs. Zu jeder API wird Folgendes angezeigt: Name der API (Interface), eine Beschreibung (Description) und, je nach gewähltem Menü, eine Klassifizierung nach Produktcode (Prod) oder Kategorie (Category).

Mit Ausnahme der Spalte Cmd befindet sich über jeder Spalte ein Auswahlfeld, in das Sie Auswahlkriterien eingeben können.

Das Eingabefeld Category im unteren Bereich des Menüs können Sie außerdem zur Suche nach verfügbaren Kategorien benutzen.

Das Eingabefeld Keywords können Sie als Suchfeld benutzen, um verfügbare Schlüsselwörter oder APIs abzurufen.

Darüber hinaus können Sie Auswahlkriterien bei mehreren Auswahlfeldern eingeben. Zum Beispiel können Sie in einem einzelnen Schritt APIs auswählen, die mit USR4 beginnen und als weitere Auswahlkriterien das Schlüsselwort PF-KEY und die Kategorie NATURAL ENVIRONMENT aufweisen.

Die folgende Tabelle enthält eine ausführliche Beschreibung aller Bestandteile des SYSEXT Utility-Menüs:

Kategorie-Suche

• Geben Sie einen Stern (*) oder ein Präfix im Suchfeld Category ein. Wahlweise können Sie einen Stern (*) zur Eingrenzung angeben, z.B.:

  N*

  Als Ergebnis der Suche erscheint ein Menü (Beispiel):

  Search for Categories Mark Category ---- N*____________________________ _ NATURAL ENVIRONMENT _ NATURAL OBJECTS

  Um eine bestimmte Kategorie als Auswahlkriterium auszuwählen, können Sie in dem entsprechenden Eingabefeld in der Spalte Mark ein beliebiges Zeichen eingeben. Als Ergebnis wird eine Liste aller APIs, die dieses Auswahlkriterium erfüllen, angezeigt.

Schlüsselwort-Suche

• Geben Sie im Feld Keyword einen Stern (*) oder ein mit einem Stern (*) eingegrenztes Präfix ein, z.B.:

  PF*

  Als Ergebnis der Suche erscheint ein Menü mit einem separaten Fenster, in dem Schlüsselwörter angezeigt werden, die mit PF beginnen (Beispiel):

  Search for Keywords Mark Keyword ---- PF*_________________ _ PF-KEY _ PF-KEY LINE

  Um ein bestimmtes Schlüsselwort als Auswahlkriterium auszuwählen, können Sie in dem entsprechenden Eingabefeld in der Spalte Mark ein beliebiges Zeichen eingeben. Als Ergebnis wird eine Liste aller APIs, die dieses Auswahlkriterium erfüllen, angezeigt.

Schlüsselwort-Auswahl

• Geben Sie ein vollständiges Schlüsselwort ein, z.B.:

  PF-KEY

  Als Ergebnis der Suche erscheint eine Liste aller APIs mit Schlüsselwort PF-KEY.

  Anmerkung:
  Ein Stern (*), der nicht am Ende eines Kriteriums angegeben wird, wird nicht als Platzhalter, sondern "buchstäblich" interpretiert. Beispiel: Die Eingabe von *LANGUAGE ergibt eine Liste mit APIs mit dem Schlüsselwort *LANGUAGE.

PF-Tasten

Sie können die folgenden, mit Funktionen belegten PF-Tasten benutzen:

Zeilenkommandos

Zeilenkommandos werden verwendet, um Objektoperationen durchzuführen. Sie können ein Zeilenkommando in der Spalte Cmd neben der gewünschten API eingeben. Für eine Liste der gültigen Zeilenkommandos können Sie ein Fragezeichen (?) eingeben oder PF1 drücken.

Folgende Zeilenkommandos stehen zur Verfügung:

Utility-Kommandos

In der Kommandozeile können Sie die folgenden Utility-Kommandos eingeben:

• EXIT
  SYSEXT Utility verlassen.

• REFRESH
  Aktualisieren der API-Informationen unter Verwendung von Daten aus den Objekten, die in der aktuellen Library SYSEXT enthalten sind. Dieses Kommando wird nur dann benötigt, wenn eine API-Beschreibung oder ein Schlüsselwort geändert oder ein Text-Objekt hinzugefügt oder entfernt worden ist.

  Nach erfolgter Aktualisierung erscheint eine Meldung zur Bestätigung, dass die Text-Module EXT-XML1 und EXT-XML2 in der Library SYSEXT generiert worden sind.

  Anmerkung:
  Sie dürfen die Source-Objekte EXT-XML1 und EXT-XML2 nicht ändern. Diese werden zum Konfigurieren der SYSEXT Utility benötigt und sind nur für den internen Gebrauch in der Software AG bestimmt.

Interface-Versionen

Interface-Versionen können als eine Sammlung von APIs gesehen werden mit (fast) der gleichen Funktionalität, aber mit unterschiedlich erweiterten Parameter Spezifikationen. Sie decken somit den Entwicklungszyklus ab, der explizit wegen der Kompatibilität (zwischen späteren und früheren Versionen) aufbewahrt wird.

Wenn Interface-Versionen zu einer API existieren, werden diese im entsprechenden Text-Objekt USRnnnnT angezeigt. Interface-Versionen sind in einer Liste gemäß der Version angeordnet, zu der sie gehören. Das ganz rechts angeordnete Listenelement gehört zu der aktuellen Version. Der Status wird durch das Schlüsselwort +CURRENT-VERSION ausgedrückt. Alle übrigen Listenelemente gehören zu früheren Versionen und sind durch das Schlüsselwort +PREVIOUS-VERSION gekennzeichnet. APIs ohne Interface-Versionen werden als singulär, d.h. nur einmal vorhanden, bezeichnet.

APIs mit Interface-Versionen werden im Menü hervorgehoben dargestellt.

Die Liste aller aktuellen APIs (siehe PF5) besteht aus allen nur einmal vorhandenen APIs und der aktuellen Version von APIs mit Interface-Versionen (mit Schlüsselwort +CURRENT-VERSION).

Reservierte Schlüsselwörter

Reservierte Schlüsselwörter beziehen sich auf Meta-Informationen zu APIs, z.B. der Natural-Version, in der eine API hinzugefügt worden ist. Reservierte Schlüsselwörter beginnen immer mit einem Plus-Zeichen (+):

Eine Natural API verwenden

Wenn Sie eine der Natural APIs, die in der System-Library SYSEXT enthalten sind, verwenden möchten, können Sie einen der folgenden Schritte ausführen:

• Definieren Sie die System-Library SYSEXT in der Systemdatei FNAT als eine Steplib Library für die Benutzer-Library, die die Natural-Objekte enthält, welche diese API verwenden. Dadurch sind bei einem Upgrade Ihrer Natural-Version keine API-spezifischen Maßnahmen erforderlich.

• Kopieren Sie die benötigte API in die System-Library SYSEXT in der Systemdatei FNAT. Sie müssen so bei einem Natural-Upgrade nur eine einzige Library auf APIs überprüfen.

• Kopieren Sie die benötigte API in die System-Library SYSTEM in der Systemdatei FNAT (nicht zu empfehlen).

• Kopieren Sie die benötigte API in die Benutzer-Library (oder in eine ihrer Steplibs) in der Systemdatei FUSER, die die Natural-Objekte enthält, welche diese API verwenden (nicht zu empfehlen).

Sie können eine API nur in der Natural-Version verwenden, in der sie ausgeliefert wird. Es wird dringend geraten, die APIs nur in der Systemdatei FNAT zu speichern. Dadurch wird sichergestellt, dass immer die richtige Version ausgeführt wird.

Um eine Natural API zu verwenden:

1. Benutzen Sie im rufenden Programm das Statement DEFINE DATA, um die Parameter anzugeben, die im Text-Objekt USRnnnnT der betreffenden API aufgelistet sind. In dem Beispiel-Programm USRnnnnP werden die Parameter in einem DEFINE DATA LOCAL-Statement definiert. Alternativ können Sie die Parameter außerhalb des rufenden Programms in einer separaten LDA (Local Data Area) oder PDA (Parameter Data Area) angeben, indem Sie ein DEFINE DATA LOCAL USING-Statement benutzen, das diesen Datenbereich referenziert.

2. Geben Sie folgendes Statement ein:

   CALLNAT 'USRnnnnN' parameters

   Weitere Informationen siehe CALLNAT-Statement in der Statements-Dokumentation.

Wenn Sie einen in der System-Library SYSEXT enthaltenen Copycode verwenden möchten, können Sie folgenden Schritt ausführen:

• Kopieren Sie den benötigten Copycode in die Benutzer-Library in der Systemdatei FUSER, die die Natural-Objekte enthält, welche diese API verwenden

Um einen Copycode zu verwenden:

1. Benutzen Sie im rufenden Programm das Statement INCLUDE, um die Parameter anzugeben, die im Text-Objekt USRnnnnT der betreffenden API oder im Copycode selbst aufgelistet sind. In dem Beispiel-Programm USRnnnnP werden die Parameter in einem DEFINE DATA LOCAL-Statement definiert. Alternativ können Sie die Parameter außerhalb des rufenden Programms in einer separaten LDA (Local Data Area) oder PDA (Parameter Data Area) angeben, indem Sie ein DEFINE DATA LOCAL USING-Statement benutzen, das diesen Datenbereich referenziert.

2. Bei einigen Copycodes sind zusätzliche Datendefinitionen erforderlich. Diese sind im Text-Objekt USRnnnnT der API und im Copycode selbst beschrieben.

3. Geben Sie folgendes Statement ein:

   INCLUDE USRnnnnX 'parameter'...

   Weitere Informationen siehe INCLUDE-Statement in der Statements-Dokumentation.