User Exits

User Exits (Benutzer-Routinen) müssen als Natural-Objekte des Typs "Subprogram" erstellt werden. Sie werden automatisch vom Entire Operations-Monitor dort aufgerufen, wo sie definiert sind.

Entire Operations-User Exits benötigen Informationen, die im Natural-Parameter-Datenbereich (PDA, Parameter Data Area) NOPXPL-A angegeben werden.

Zum Erstellen von User Exits müssen Sie den Entire Operations Editor benutzen (siehe auch JCL oder Natural-Programme editieren im Abschnitt Job-Verwaltung) und dabei die Einschränkungen beachten, die im Abschnitt Einschränkungen für das Programmieren von User Exits aufgeführt sind.

Dieser Abschnitt behandelt folgende Themen:


Funktionsumfang von User Exits

User Exits können benutzt werden, um Job-Ergebnisse zu überprüfen und den Jobfluss durch ihre Rückgabe-Werte zu beeinflussen. Doch neben diesen Lauf-Prüfungen erlaubt die Benutzung von Entire System Server und Adabas-Technologie weiterführende Aktionen mit User Exits, zum Beispiel:

  • Datenbank-Aktualisierungen

  • Dateizugriffsverwaltung

  • Zugang zu Betriebssystem-Funktionen

  • Plausibilitätsprüfungen

User Exits für den Monitor können jede Adabas- oder Entire System Server-Funktion durchführen, aber keine Bildschirm-Ein-/Ausgabe-Funktionen.

Entire Operations prüft die Existenz eines User Exit, während er definiert wird, genauso wie beim Aufruf. Entire Operation behandelt das Nichtvorhandensein eines User Exit als Fehler. Wenn ein solcher Fehler beim Aufruf und während der Job-Durchführung erscheint, wird die Netzwerk-Ausführung unterbrochen.

User Exits können den Entire Operations-Jobfluss betreffen, wenn sie, je nach Typ und Ergebnis der Routine, einen Rückgabewert oder andere Informationen nach der Ausführung zum Aufrufer zurücksenden.

Anmerkungen:

  1. User Exits können vom Entire Operations-Monitor aufgerufen werden, welcher sie als Subroutine durchführt. Bitte beachten Sie, dass die intensive Nutzung von User Exits die sonstige Arbeit des Monitors beeinflussen kann.
  2. Beachten Sie beim Programmieren die Einschränkungen für das Programmieren von User Exits.

Globale User Exits

Sie können User Exits definieren, die global für Ihre Entire Operations-Umgebung gültig sind. Weitere Informationen siehe folgende Abschnitte in der Systemverwaltung-Dokumentation:

Front-End User Exits

Front- End User Exits werden als Natural-Objekt des Typs "Subprogram" erstellt. Sie werden vom Entire Operations Front-End aufgerufen.

Sie können jede benutzerdefinierte Maske mit den folgenden Restriktionen benutzen:

  • Die Maske (Natural-Objekt-Typ M, Map/Maske) muss von der Entire Operations-Bibliothek SYSEOR aus erreichbar sein. Der einfachste Weg hierfür ist das Kopieren der benötigten Masken in die Entire Operations-Bibliothek.

  • Beachten Sie, dass Entire Operations mit den folgenden Natural-Sprachcodes ausgeführt werden kann: 1 = Englisch; 2 = Deutsch. Daher ist es nützlich, zwei Masken zu liefern und diese mit einem Und-Zeichen (&) als Platzhalter für den aktuellen Sprachcode zu referenzieren.

    Weitere Informationen siehe Abschnitt Mehrsprachige Benutzeroberflächen im Natural-Leitfaden zur Programmierung.

Sie können die folgenden Front-End User Exits definieren:

  • Symbolabfragen für ein Netzwerk oder eine Job-Aktivierung.

    Weitere Informationen siehe Symbolabfragen bei der manuellen Aktivierung im Abschnitt Netzwerk-Verwaltung.

Allgemeiner User Exit-Parameterdatenbereich NOPXPL-A

Alle User Exits unter Entire Operations müssen den allgemeinen Parameterdatenbereich NOPXPL-A aufweisen, welcher sowohl im Objekt- als auch im Quellformat in der Bibliothek SYSEOR vorhanden ist.

Daher muss der Code des User Exit immer folgendermaßen beginnen:

DEFINE DATA PARAMETER USING NOPXPL-A

Dieser Abschnitt behandelt folgende Themen:

User Exit-Typen, P-CALL-PLACE

Das Feld P-CALL-PLACE in der Parameter-Liste gibt an, zu welchem Zweck der User Exit aufgerufen wurde:

P-CALL-PLACE Bedeutung
EJA   Job-Ende-Aktion

Siehe auch Job-Ende-Aktions-Exit definieren im Abschnitt Job-Ende-Prüfungen und -Aktionen.

EJC   Job-Ende-Prüfung

Siehe auch User Exits für Job-Ende-Prüfungen oder Aktionen erstellen oder bearbeiten im Abschnitt Job-Ende-Prüfungen und -Aktionen.

FSB   SYSOUT Dateinamen-Generierung (BS2000)

Siehe auch NOPFB2-N und NOPXPL-A - SYSOUT-Dateinamen für BS2000 generieren im Abschnitt API-Routinen.

ICO   Eingabebedingung-Wertbestimmung

Siehe auch Eingabebedingung abhängig von User Exit im Abschnitt Job-Definition anlegen.

MAC   Dynamische JCL-Generierung

Siehe auch Dynamische JCL-Generierung (JCL-Speicherart MAC) im Abschnitt Systemübersicht.

NAT   Natural-Programm-Standalone unter Entire Operations (NAT-Typ Job)

Siehe auch Jobtypen und Job-Ausführungsmerkmale im Abschnitt Job-Verwaltung.

NVN Globaler User Exit für Versionsnamen

Siehe auch Globaler Exit für Versionsnamen in der Systemverwaltung-Dokumentation.

RMD   Ressource-Bestimmungs-Exit

Siehe auch Ressource-Bestimmungs-Exit in der Systemverwaltung-Dokumentation.

SFX   Symbol-Funktions-Exit

Siehe auch User Exits für Symbol-Funktionen.

SNF   Globaler "Symbol nicht gefunden"-Exit

Siehe auch Globaler "Symbol nicht gefunden"-Exit in der Systemverwaltung-Dokumentation.

SVN Name der Syboltabellen-Version, Syntax-Prüfung

Siehe auch Globaler Exit für Versionsnamen in der Systemverwaltung-Dokumentation.

SYC   Symbol-Plausibilitäts-Prüfung (Gültigkeitsprüfung)

Siehe auch User Exit für Plausibilitätsprüfung von Symbolen.

SYF Symbol-Funktionen

Siehe auch User Exits für Symbol-Funktionen.

Parameter für verschiedene Aufruforte

Feldname Format Aufrufort (Call Place)
P-CALL-PLACE A03 EJA EJC FSB ICO MAC NAT NVN RMD SFX SNF SVN SYC SYF
P-RC
(Rückgabe-Code)
N04 out out out out n/a out out out out out out out out
P-RT
(Rückgabe-Text)
A66 out out out out n/a out out out out out out out out
P-OWNER  A10 in in in in in in in in in in in in in
P-NETWORK  A10 in in in in in in in in in in in (3) in
P-NETWORK-VERSION-1 A10 n/a n/a n/a n/a n/a n/a in n/a n/a n/a n/a n/a n/a
P-JOB  A10 in in in in in in n/a in in in n/a n/a in
P-RUN  P13 in in in in in in n/a in in in n/a (3) in
P-ACTIVATION-TIME  T in in in in in in n/a in (7) n/a n/a n/a (3) n/a
P-EXECUTION-NODE  (10) N03 in in in in in in n/a in in in n/a n/a in
P-EXECUTION-OPSYS  A08 in in in in in in n/a in n/a n/a n/a n/a n/a
P-SYMTAB  A10 in in in in in in n/a in in in n/a n/a in
P-SYMTAB-VERSION-1 A10 n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a in n/a n/a
P-CONDITION  A20 (6) (6) n/a in (2) n/a n/a n/a n/a n/a n/a n/a n/a
P-RESOURCE A20 in n/a n/a n/a n/a n/a n/a in n/a n/a n/a n/a n/a
P-SYMBOL (13) A20 (1) n/a n/a n/a n/a n/a n/a n/a n/a mod n/a n/a in
P-JOB-ID A10 out out n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-JOB-NUMBER  (9) N05 out out n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-SYSOUT-FILE (11)  A54 (1) (1) out n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-FSB-OBJECT-TYPE  A05 n/a n/a in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-FSB-USERID  A08 n/a n/a in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-FSB-CATID  A04 n/a n/a in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-FSB-SUFFIX  A02 n/a n/a in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-SYMBOL-VALUE (14) A54 n/a n/a n/a n/a n/a n/a n/a n/a n/a out n/a n/a in
R-RMD-OLD-QTY-INITIAL
N7.2 n/a n/a n/a n/a n/a n/a n/a in n/a n/a n/a n/a n/a
P-RMD-NEW-QTY-INITIAL
N7.2 n/a n/a n/a n/a n/a n/a n/a out n/a n/a n/a n/a n/a
P-RMD-PARAMETER
A36 n/a n/a n/a n/a n/a n/a n/a in n/a n/a n/a n/a n/a

Dabei bedeutet:

n/a = Parameter kann ungültige Werte enthalten, nicht ändern.

in = Parameter enthält Eingabewerte.

out = Parameter enthält Ausgabewerte.

mod = Parameter-Änderungen werden gespeichert.

Anmerkungen:

1 in; nur BS2000.
2 in; enthält P-SUFFIX in den ersten 10 Bytes.
3 in; nur für aktive Symbole.
6 in; enthält P-JOB-ID (A5) in den ersten 5 Bytes.
7 in; hier: Zeitstempel des vorangegangenen Exit-Aufrufs.
9 Dieses Feld soll nicht mehr benutzt werden. Benutzen Sie stattdessen P-JOB-ID-10. Die Größe von P-JOB-NUMBER ist für manche Betriebssysteme zu klein. Aus Kompatibilitätsgründen wird dieses Feld im Gegenzug gefüllt, wenn die Job-Nummer im Bereich von 1 bis 99999 ist.
10 Knotennummern von 1 - 999 werden hier zur Verfügung gestellt. P-EXECUTION-NODE ist bei Knotennummern höher als 999, P-EXECUTION-NODE ist Null. Knotennummern mit beliebiger Größe werden in der unabhängigen Variablen (AIV) +P-EXEC-NODE-I4 "I4" zur Verfügung gestellt.
11 Bei längeren Dateinamen muss die unabhängige Variable (AIV) +P-SYSOUT-FILE-250 (A250) verwendet werden.
13 Dieses Feld wird nur aus Kompatibilitätsgründen gepflegt: Parameteränderungen mit internem Format/Wertlänge A40 können Werte abschneiden und somit zu Datenverlust führen.
14 Dieses Feld wird nur aus Kompatibilitätsgründen gepflegt: Parameteränderungen mit internem Format/Wertlänge A80 können Werte abschneiden und somit zu Datenverlust führen.

Zusätzliche unabhängige Variablen (AIV)

Zusätzlich zur Parameterliste in NOPXPL-A stehen einige Parameter als unabhängige Variablen (AIV) zur Verfügung.

Feldname Format Aufrufort
    EJA EJC FSB ICO MAC NAT NVN RMD SFX SNF SVN SYC SYF
+P-NETWORK-VERSION A10 in in in in in in in in in in in n/a in
+P-SYMTAB-VERSION A10 in in in in in in n/a in in in n/a n/a in
+P-EXEC-NODE-I4 I04 in in in in in in n/a in in in n/a in in
+P-SYSOUT-FILE-250 A250 in in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
+P-JI-JOB-TYPE A03 in in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
+P-JI-DUMMY-FLAG A01 in in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a

Feldbeschreibungen

+P-NETWORK-VERSION Version des Netzwerks.
+P-SYMTAB-VERSION Version der Symboltabelle.
+P-EXEC-NODE-I4 Diese Feld liefert Knotennummern jeder beliebigen Größe (1 bis 99999). Es ist zu jeder Knotennummer vorhanden. Sie müssen es anstelle von P-EXECUTION-NODE benutzen, wenn die Knotennummer höher als 999 ist.
+P-SYSOUT-FILE-250 Dieses Feld liefert den SYSOUT-Dateinamen in einem Feld mit einer Länge von 250 Bytes. Sie müssen dieses Feld für den Namen der SYSOUT-Datei bei einem UNIX- oder Windows-Job (anstelle von P-SYSOUT-FILE) benutzen, um eine Abschneidung zu vermeiden.
+P-JI-JOB-TYPE Der Jobtyp des Jobs. Siehe auch Jobtypen und Job-Ausführungsmerkmale im Abschnitt Job-Verwaltung.
+P-JI-DUMMY-FLAG Grund, warum ein Job zu einem temporären Dummy-Job wurde ("dummy due to …").
'J' JCL-Prüfung.
'D' Definition.
'S' Zeitplan.
'R' Wiederherstellung.
'T' Wiederholung.
'E' Empty (leere) JCL.
'C' Bedingung.
'M' Multiples Suffix.
'K' Zu deaktivieren.

Vordefinierte Symbole

Siehe Vordefinierte und reservierte Symbole im Abschnitt Symbole.

Allgemeine Anmerkungen zu User Exits

Alle User Exits müssen das Feld P-RC (Rückgabe-Code) zurückgeben. 0 (Null) bedeutet OK.

Das Feld P-RT (Rückgabe-Text) kann optional benutzt werden, um spezifische Informationen zurückzugeben. Entire Operations schreibt diesen Text in das Protokoll und zeigt ihn auf dem Aktiven-Job-Bildschirm an.

Alle anderen Parameter übergeben Umgebungs-Informationen an den User Exit. Einige Parameter und AIV-Variablen sind nicht immer erforderlich. Weitere Informationen siehe obige Tabelle.

Dezimal-Zeichen-Einstellungen (Natural-Profilparameter DC)

Der Parameterdatenbereich NOPXPL-A enthält Nummen mit Dezimalzeichen. Die Standard-Einstellung für das Dezimal-Zeichen im ausgelieferten Quellcode von NOPXPL-A ist der Punkt (.). Wenn Sie Ihre User Exits und Natural-Programme mit anderen Dezimal-Zeichen katalogisieren wollen (z.B. Komma, mittels Natural-Profilparameter DC=,), müssen Sie auch NOPXPL-A verändern:

Beginn der AnweisungslisteUm die Dezimal-Zeichen-Einstellungen zu ändern

  1. Stellen Sie sicher, dass die Dezimal-Zeichen Ihrer Natural-Session korrekt gesetzt sind. Sie können dies mit dem Natural-Systemkommando GLOBALS überprüfen.

  2. Benutzen Sie den Natural Editor, um NOPXPL-A zu bearbeiten.

  3. Ändern Sie die Dezimal-Zeichen entsprechend ihrer aktuellen DC-Parameter-Einstellungen in den numerischen Feldern, welche Dezimal-Zeichen enthalten.

  4. Speichern Sie NOPXPL-A.

    Sie können nun NOPXPL-A mit Ihren eigenen Dezimal-Zeichen benutzen.

Einschränkungen für das Programmieren von User Exits

  1. ON ERROR-Routinen dürfen in Entire Operations User Exitsprogrammiert werden. Es gilt folgende Einschränkung:

    Der ON ERROR-Statement-Block darf nicht mittels eines der folgenden oder eines ähnlichen Statements verlassen werden:

    • ESCAPE ROUTINE

    • ESCAPE MODULE

    • TERMINATE

    Zweck dieser Einschränkung ist es sicherzustellen, dass nach Ausführung des benutzerdefinierten ON ERROR-Statement-Blocks der gemeinsame Entire Operations Monitor (oder Entire Operations Online) die Kontrolle erhält. Die gemeinsame Entire Operations-Fehlertransaktion führt einige generelle Massnahmen durch (Fehlerbehandlung, Protokollierung, Benachrichtigungen usw.).

  2. Es dürfen keine Programme mit ihrer eigenen GDA aufgerufen werden.

  3. Die Namen der User Exits dürfen nicht mit dem Buchstaben V beginnen. Dies gilt vor allem, wenn sie in der Bibliothek SYSEOR gespeichert werden sollen, weil das Präfix V für das interne Entire Operations Exit-Verzeichnis reserviert ist.

  4. Die folgenden Natural-Statemens dürfen in keiner Routine programmiert werden, die von Entire Operations aufgerufen wird:

    • END TRANSACTION - Die Transaktionslogik wird vom Entire Operations-Monitor selbst verwaltet.

    • BACKOUT TRANSACTION

    • STOP

    • TERMINATE

    • FETCH ohne RETURN (FETCH RETURN ist zulässig)

  5. Anmeldungen bei und Abmeldungen von Entire System Server-Knoten sollten vermieden werden. Das gilt für Großrechner-Knoten (View NATPROC-LOGON), UNIX-Knoten und Windows-Knoten. Falls in einem User Exit irgendwelche Anmeldungen und/oder Abmeldungen erfolgt sind, muss der Exit vor der Beendigung die Entire System Server-Knoten-Aufhebung (API NOPUNI1N) aufrufen. Dadurch erfolgen nachfolgende neue Anmeldungen zwangsweise auf diese Knoten.

  6. In User Exits dürfen keine Bildschirm- und Masken-Eingaben bzw. Ausgaben programmiert werden. Eine Ausnahme bildet der User Exit zur Symboleingabeaufforderung bei Verwendung im Online-Betrieb.

  7. Die von User Exits aufgerufenen Unterobjekte (Unterprogramme usw.) müssen sich in der Bibliothek SYSEORU befinden.

  8. Im Allgemeinen ist die Ausführung aller Arten von Code, der den Entire Operations-Monitor stören könnte, in User Exits verboten. Bei Unsicherheiten, wenden Sie sich bitte an den Software AG Support.

Anmerkungen:

  1. Wenn Sie die Werte der speziellen Parameter in der Macro-JCL nutzen wollen, müssen Sie sie zuerst mit dem speziellen Statement #GET-SYMBOL auslesen. Siehe #GET-SYMBOL in Symbole und Lokale Variablen.
  2. Bei Verwendung im Vordergrund können bei diesem Exit Masken verwendet werden (mit einigen Einschränkungen).

Generierung dynamischer JCL und von SYSOUT-Dateinamen (nur bei BS2000)

Bei Jobs des Typs MAC können Sie dynamische JCL generieren. Siehe Dynamische JCL-Generierung (JCL-Speicherart MAC) im Abschnitt Systemübersicht.

In einer BS2000-Umgebung können Sie Dateinamen für die SYSOUT-Datei generieren. Siehe NOPFB2-N und NOPXPL-A - SYSOUT-Dateinamen für BS2000 generieren im Abschnitt API-Routinen.

Natural-Programme, die als Jobs innerhalb eines Job-Netzwerkes definiert wurden (NAT-Typ Jobs)

In Entire Operations können Sie Natural-Programme als Jobs vom Typ NAT innerhalb von Job-Netzwerken definieren. Sie haben keine JCL und werden direkt vom Entire Operations-Monitor ausgeführt. Wie alle Jobs, werden Jobs vom Typ NAT über das Entire Operations-Netzwerk und die Job-Verwaltung definiert.

Sie können Jobs vom Typ NAT wie alle anderen Jobs pflegen, das heißt, Sie können sie mit Eingabebedingungen, Ausgabebedingungen, Ressourcen usw. ausstatten.

Weitere Informationen siehe Job-Verwaltung.

User Exit zur Master-Ressource-Bestimmung

Ein User Exit zur Bestimmung der Ressourcenmenge kann für jede Master-Ressource definiert werden. Siehe Ressource-Bestimmungs-Exit in der Systemverwaltung-Dokumentation.

User Exits zum Setzen von Eingabebedingungen

Bevor Entire Operations einen Job freigeben kann, müssen alle Eingabebedingungen erfüllt sein.

Wenn ein User Exit für eine Bedingung definiert ist, ruft Entire Operations, jedes Mal wenn der Bedingungsstatus überprüft wird, den definierten Exit (vom Typ ICO) auf. Die Bedingung ist erfüllt, wenn der Exit im Parameter P-RC den Wert Null zurückgibt.

Andernfalls wird die Bedingungsprüfung fortgesetzt.

Sie können im Parameter P-RT zusätzlich einen Rückgabetext setzen.

User Exits für die Job-Ende-Prüfung und -Aktionen

Sie können User Exits als einen Teil der Job-Ende-Prüfung definieren. Die Job-Ende-Prüfung von Entire Operations basiert auf dem Erscheinen definierter Ereignisse während der Ausführung des Jobs. Sie können User Exits als Ereignis-Prüfungen definieren. Entire Operations führt automatisch die User Exits aus, wenn der Job endet.

Typischerweise kann eine solche Routine das Ergebnis eines Jobs überprüfen. Der User Exit gibt den Code zurück der den Ereignis-Status bestimme. Ein zurückgegebener Code 0 bedeutet, das die Prüfung fehlerfrei ist. Ein anderer Code bedeutet, dass die Prüfung fehlerhaft ist. Bedingungs-Codes, die von User Exits zurückgegeben werden, können die Status des Job-Endes bestimmen.

Job-Ende-Aktionen können genutzt werden, um alle Aktionen nach Job-Ende durchzuführen.

Job-Ende-Prüfungen und Aktions-Exits werden mit der Job-Nummer und dem Namen der SYSOUT-Datei versehen, in der Entire Operations die Job-SYSOUT sammelt (nur bei BS2000).

Bei User-Exits für Job-Ende-Prüfungen und -Aktionen muss die allgemeine Exit-Parameterliste NOPXPL-A benutzt werden. Der Parameter P-CALL-PLACE enthält EJC bei User Exits zur Job-Ende-Prüfung bzw. EJA bei User Exits für Job-Ende-Aktionen.

Verwandtes Thema:

Dieser Abschnitt behandelt folgende Themen:

Beispiel

Der im folgenden Beispiel gezeigte User Exit für Job-Ende-Prüfungen summiert den Inhalt eines numerischen Feldes im SYSOUT auf und vergleicht ihn mit einem gegebenen Wert. Wenn beide gleich sind, ist das Ereignis ok, ansonsten ist es nicht ok.

DEFINE DATA PARAMETER USING NOPXPL-A
LOCAL
1 READ-SPOOL VIEW OF READ-SPOOL      /* AN ENTIRE SYSTEM SERVER VIEW
  2 RECORD
  2 REDEFINE RECORD
    3 RECORD-HEADER    (A05)
*
1 #NF              (I02) CONST <10>   /* MAX. NUMBER FOR SEPARATION
1 #SUM             (N08) INIT  <0>
1 #SUM-EXPECTED    (N08) CONST <2000>
1 #FIELD           (A10/1:#NF)
1 #USERID          (A08)
1 #DBENV           (A10)
1 #NETWORK-VERSION (A10)
 
1 #LOG-STATUS      (N04)
1 #LOG-MESSAGE     (A60)
1 #LOG-TARGET      (A03) CONST <’NOP’>     
1 #USE-NAT-MSG-CACHE (L) CONST <FALSE>
END-DEFINE
* -------------------------------------------------
* This EOJ User Exit will read the Job SYSOUT (data set 2)
* and will summarize a defined field.
* If the sum is equal to a given value, this routine returns
* an 'OK' (P-RC = 0), otherwise 'NOT OK'.
*
* A log record will be written to document the result.
*
RESET #SUM
RS. FIND READ-SPOOL
    WITH NODE = P-EXECUTION-NODE AND JOB-NUMBER = P-JOB-ID
    AND TYPE = 'SO' AND DATA-SET = 2 AND RECORD-NUMBER >= 1
  ACCEPT IF RS.RECORD-HEADER = 'REC01'     /* interesting only
  SEPARATE RS.RECORD LEFT JUSTIFIED INTO #FIELD(*)
  ADD VAL(#FIELD(3)) TO #SUM
END-FIND
*
IF #SUM = #SUM-EXPECTED
  RESET P-RC
  MOVE 'Sum check is ok' TO #LOG-MESSAGE
ELSE
  MOVE 1 TO P-RC
  COMPRESS 'Sum:' #SUM 'Expected:' #SUM-EXPECTED INTO #LOG-MESSAGE
END-IF
#USERID := *USER
MOVE 9999 TO #LOG-STATUS
CALLNAT 'NOPULW93N'          /* WRITE LOG RECORD
  #LOG-STATUS #LOG-MESSAGE #DBENV 
  P-OWNER P-NETWORK #NETWORK-VERSION P-RUN P-JOB 
  P-JOB-ID #LOG-TARGET # USE-NAT-MSG-CACHE
END

User Exits für Symbol-Funktionen

Über einen User Exit können Sie benutzerspezifische Symbol-Funktionen ausführen. Verfügbare Symbol-Funktionen siehe Funktionen zur Symbolersetzung im Abschnitt Symboltabellen und Symbole verwalten.

Dieser Abschnitt behandelt folgende Themen:

Syntax für Symbol-Funktionen

§!|?function[parm,...]

Kodierungsregeln für Symbol-Funktionen

  • Bei User Exits müssen stets die Einschränkungen für das Programmieren von User Exits beachtet werden.

  • Damit eine Funktion erkannt wird, muss nach dem Fluchtzeichen immer ein Ausrufezeichen (!) oder Fragezeichen (?) folgen. In BS2000 wird das Ausrufezeichen (!) durch den Buchstaben ö dargestellt.

  • Die Parameterliste ist optional und wird in eckige Klammern ([ ]) eingeschlossen. Zwischen Funktionsname und Parameterliste sind keine Leerzeichen erlaubt

  • Parameter müssen durch Kommas getrennt werden.

  • Die Gesamtlänge des Funktionsaufrufs darf nicht länger als 20 Zeichen sein.

  • Die Symbolfunktionen müssen in der Bibliothek SYSEOR abgelegt werden.

  • Die Parameter werden der Funktion in einem extra Feld übergeben.

  • Das Protokollieren (Logging) der Symbolersetzung wird vom Entire Operations-Monitor ausgeführt. Zusätzliches Protokollieren ist freigestellt.

  • Der Symbolwert wird nach erfolgreicher Ersetzung in die aktive Symboltabelle des Jobs zurückgeschrieben. Bei Folge-Ersetzungen wird nicht mehr die Symbol-Funktion aufgerufen, sondern der Wert aus der aktiven Tabelle gelesen.

Die Namen der Symbolfunktions-Exits beginnen mit SX. Da die Namenslänge der Natural-Objekte auf 8 Zeichen begrenzt ist, darf der Funktionsname - das Ausrufezeichen (!) zählt nicht - maximal 6 Zeichen haben.

Symbol-Funktion - Parameter-Liste

Die Funktion !RANDOM wird vom Natural-Subprogramm SXRANDOM behandelt.

Die Symbolfunktions-Exits werden mit der Parameterliste NOPXPL-A aufgerufen. Die erste Zeile des Exits sollte somit lauten:

DEFINE DATA PARAMETER USING NOPXPL-A

Parameter in NOPXPL-A:

Parameter
P-CALL-PLACE 
P-RC 
P-RT 
P-OWNER 
P-NETWORK 
P-JOB 
P-RUN 
P-EXECUTION-NODE 
P-SYMBOL-TABLE 
P-SYMBOL 
P-SYMBOL-VALUE 
Hinweise:
  1. Vom Aufrufenden gelieferter SFX (Symbolfunktions-Exits) für P-CALL-PLACE.

  2. Setzen Sie P-RC auf einen der beiden folgenden Rückgabe-Codes:

    0 (Funktion ok.) oder

    4531 (Symbol nicht gefunden.)

  3. Im Feld P-SYMBOL werden nur die Funktionsparameter (ohne Klammern) übergeben. Den Funktionsnamen kann man aus der Natural-Systemvariablen *PROGRAM entnehmen (Beschreibung siehe Natural-Systemvariablen-Dokumentation.

Beispiel für eine Symbol-Funktion

User Exit Subprogram SXQS

* SYMBOL FUNCTION EXIT EXAMPLE
* SXQS<PARM1>
* CROSSFOOTING OF THE PARAMETER
* -------------------------------------------------------------
DEFINE DATA PARAMETER USING NOPXPL-A
LOCAL
1 #I   (I02)
1 #N   (I02)
1 #SUM (I02)
1 #A   (A01)
END-DEFINE
* -------------------------------------------------------------
RESET #SUM
F1. FOR #I = 1 TO 20
  #A := SUBSTR (P-SYMBOL,#I,1)
  IF #A IS (N1)
    #N := VAL(#A)
    ADD #N TO #SUM
  END-IF
END-FOR    /* F1.
P-SYMBOL-VALUE := #SUM
RESET P-RC P-RT
END

Master JCL

//SN000001 JOB ,SN,CLASS=K
//IEFBR14  EXEC PGM=IEFBR14
//*
//* +!D<AQ+1>
//* §!D<AQ+1>
//*
//* +!QS<4711>
//* §!QS<4711>
//*
//* +!QS<+*DATE>                 NESTED Symbole
//* +!QS<§*DATE>                 NESTED Symbole
//* §!QS<§*DATE>                 NESTED Symbole
//*
//* +!QS<+!D<AM-1>>              NESTED FUNCTIONS
//* +!QS<§!D<AM-1>>              NESTED FUNCTIONS
//* §!QS<§!D<AM-1>>              NESTED FUNCTIONS
//*

Aktive JCL

//SN000001 JOB ,SN,CLASS=K
//IEFBR14  EXEC PGM=IEFBR14
//*
//* +!D<AQ+1>
//* 20081117
//*
//* +!QS<4711>
//* 13
//*
//* +!QS<+*DATE>                 NESTED Symbols
//* +!QS<17/11/08>               NESTED Symbols
//* 18                           NESTED Symbols
//*
//* +!QS<+!D<AM-1>>              NESTED FUNCTIONS
//* +!QS<20081117>               NESTED FUNCTIONS
//* 30                           NESTED FUNCTIONS
//*

Aktive Symboltabelle

Symbol            F A Value                        modified by
!D<AM-1>          A E 20080131                     EORMON   11.01.08 17:25
!D<AQ+1>          A E 20080101                     EORMON   11.01.08 17:25
!QS<11/01/08>     A E 20                           EORMON   11.01.08 17:25
!QS<20080131>     A E 15                           EORMON   11.01.08 17:25
!QS<4711>         A E 13                           EORMON   11.01.08 17:25
X                 A E x                            SN       10.11.08 13:13

User Exit zur Gültigkeitsprüfung von Symbolen

Sie können eine User Exit-Routine (Front-End User Exit) schreiben, die Ihre eigenen Eingabeaufforderungsbildschirme und Validierungsprüfungen (Gültigkeitsprüfungen) für die Symboleingabe während einer Job-Aktivierung definiert. Weitere Informationen siehe Symboleingabe im Kapitel Symboltabellen und Symbole.

Der User Exit wird vom Entire Operations-Monitor nach Erstellung der aktiven Symboltabellen, aber vor dem Laden der JCL aufgerufen. Falls der User Exit fehlt oder einen Laufzeit-Fehler bekommt, wird die Netzwerk-Aktivierung abgebrochen und eine Nachricht wird an die Mailbox gesendet, die dem Netzwerk als Nachrichten-Empfänger zugeordnet ist. Ist keine Mailbox zugeordnet, wird die Nachricht an die Mailbox SYSDBA gesendet. Weitere Informationen zu Mailboxen siehe Mailboxen.

Benutzen Sie, um die User Exit-Routine zu schreiben, den dafür vorgesehenen Parameterdatenbereich NOPXPL-A und die Parameter-Liste NOPSYP3A.

Der Parameterdatenbereich NOPXPL-A entält den Eigentümer, die Symboltabelle, den Symbolnamen usw. Er kann daher für verschiedene Symbole verwendet werden.

Die Parameter-Liste NOPSYP3A enthält alle benötigten Umgebungsparameter. Die für diese Netzwerk-Aktivierung benutzte Symboltabellenliste wird an die Entire Operations API Routine übergeben.

Die Symbole müssen von der Entire Operations API Routine NOPUSYxN gelesen werden. Diese ermöglicht das sequenzielle Lesen in der aktiven Symboltabelle. Das x bezeichnet eine sequenzielle Versionsnummer von 1 bis 6. Dabei bedeutet 6 die aktuellste Version der API.

Die Parameter P-RC (Rückgabe-Code) und P-RT (Rückgabe-Text) werden vom Aufrufenden nach Ausführung des User Exit geprüft. Wenn P-RC gleich Null ist, wird das Symbol als "ok" angenommen. Andernfalls wird es nicht angenommen.

Falls der Text in P-RT nicht leer ist, wird er dem Benutzer zusammen mit dem Nachrichtencode EOR1855 angezeigt. Wenn P-RT ungleich 0 ist und P-RT leer ist, wird eine Standard-Fehlermeldung angezeigt.

Wie in anderen User Exits können Adabas, Entire System Server und Natural-Systemvariablen zur Flexibilisierung der Symbolprüfung beitragen.

Dieser Abschnitt behandelt folgende Themen:

Parameter-Liste NOPSYP3A

*    NOPSYP3A
*    Entire Operations
*    Exit parmlist
*    for symbol prompting
*
*    27.09.12 N1399    SN541                       /* successor of NOPSYP2A
*    11.03.13 N1574    SN541                       /* N1574
*    20.08.13 N1649    SN541                       /* P-USED-SYMTAB-34
*    --------------------------------
   1 P-CALL-PLACE                     A          3
*      'SYP'  symbol prompting online
*      'SYM'  symbol modif     batch
   1 P-RC                             N          4 /* in/out  return code
*      0  out: ok
*      1  out: no symbols prompted                                           D
*      2  out: activation cancelled                                          ED
*      4  out: end (no modification)                                         ON)
*
*      3  in:  rewrite modified                                              YMBOLS*
*              symbols to symbol                                             40918)
*              master too                                                    40918)
   1 P-RT                             A         70 /* out  return text
*
   1 P-OWNER                          A         10 /* in
   1 P-NETWORK                        A         10 /* in
   1 P-NETWORK-VERSION                A         10 /* in  312641 add
   1 P-RUN                            I          4 /* in  312641 fmt, order
   1 P-JOB                            A         10 /* in  312641 order
   1 P-ACTIVATION-TIME                T            /* in
   1 P-EARLIEST-START                 T            /* in
   1 P-NETWORK-SYMTAB                 A         10 /* in                     E
R  1 P-NETWORK-SYMTAB                              /* REDEF. BEGIN : P-NETWORK-SYMT
   2 P-NETWORK-SYMBOL-TABLE           A         10 /* 312641.3
   1 P-NETWORK-SYMTAB-VERSION         A         10 /* 312641 add             E
   1 P-USED-SYMTAB-34                 A         34 (1:V) /* N1649
*      -- Use LDA NOPSYT1L for the                 N1649
*      -- layout / redefinition of                 N1649
*      -- the table elements.                      N1649
   1 P-DATE-FORMAT                    A          1 /* in
*      'A' American
*      'E' European
*      'G' German
*      'I' International
*
*    -- end of parameter area --

Dieser Abschnitt behandelt folgende Themen:

Vom Aufrufenden bei Eingabe gelieferter Rückgabe-Code

P-RC Bedeutung
3 Bei Eingabe: Geänderte Symbole in die Master-Symboltabelle zurückschreiben.

Von dem Symboländerungs-User Exit zu setzende Rückgabe-Codes

P-RC Bedeutung
0 Ok, Änderungen durchgeführt.
1 Ok, keine Symbole abgefragt oder geändert.
2 Aktivierung abgebrochen.
4 Ende. Keine Änderung.

Symbole ändern ohne Eingabe

Kodieren Sie den User Exit analog zum User Exit zur Symboleingabe.

Verwenden Sie die dafür vorgesehene Parameterliste NOPSYP3A in Verbindung mit der LDA (Local Data Area) NOPSYT1L.

Kodieren Sie keine Bildschirm-Ein-/Ausgaben, wenn Sie keine Eingabeaufforderung im Vordergrund verwenden.

Local Data Area NOPSYT1L

Das Layout des Feldes P-USED-SYMTAB-34 wird in der Data Area NOPSYT1L angegeben.

*    NOPSYT1L
*    'Symbol tables used'
*    table entry
*
*    Maintenance
*    13.08.13  N1649     SN541                     created
*    07.10.13  N1649.A   SN541                     'origin object type' val.
*    --------------------------------              -------------------------
*    -- values for SYTU-SYMTAB-STATUS
*
   1 SYTU-SYMTAB-STATUS-EV-DUP        A          2 CONST<'ED'>
*    -- effective symbol table
*    -- version is a duplicate --
*    -- entry should be skipped
*    -- during prompting
   1 SYTU-SYMTAB-STATUS-UNDEF         A          2 CONST<'00'>
*    -- undefined
   1 SYTU-SYMTAB-STATUS-NPN           A          2 CONST<'10'>
*    -- no prompting necessary
   1 SYTU-SYMTAB-STATUS-PN            A          2 CONST<'20'>
*    -- prompting necessary
   1 SYTU-SYMTAB-STATUS-PD            A          2 CONST<'30'>
*    -- prompting done
*
*    --------------------------------
*
*    -- values for
*    -- SYTU-ORIGIN-OBJECT-TYPE
*
   1 SYTU-ORIGIN-OBJECT-NV            A          2 CONST<'NV'>
*    -- network version definition
   1 SYTU-ORIGIN-OBJECT-JM            A          2 CONST<'JM'>
*    -- job (master) definition
   1 SYTU-ORIGIN-OBJECT-IM            A          2 CONST<'IM'>
*    -- input cond. (mult. suffix)
   1 SYTU-ORIGIN-OBJECT-IS            A          2 CONST<'IS'>
*    -- input cond. (dep. on symbol)
   1 SYTU-ORIGIN-OBJECT-AS            A          2 CONST<'AS'>
*    -- EOJ action (symbol setting)
*
*    --------------------------------
*
   1 SYTU-ENTRY-34                    A         34
R  1 SYTU-ENTRY-34                                 /* REDEF. BEGIN : SYTU-ENTRY-34
   2 SYTU-SYMTAB-STATUS               A          2
*    -- values see above
   2 SYTU-ORIGIN-OBJECT-TYPE          A          2
*    -- values see above                           /* N1649.A
*    ...
   2 SYTU-SYMTAB                      A         10
   2 SYTU-SYMTAB-VERSION-DEFINED      A         10
   2 SYTU-SYMTAB-VERSION-EFFECTIVE    A         10
*      blank:
*        not determined yet
*      KVE-TEXT-UNNAMED = '(none)'
*        determined and blank
*      other:
*        determined and non-blank
*
*    -- end of area --