Aufruf einer benutzerdefinierten Anweisung

Durch Eingabe des definierten Benutzeranweisungssymbols (spec) für eine benuzerdefinierte Anweisung wird diese als Unterprogramm gestartet.

Der Anweisungsroutine kann ein beliebiger Text übergeben werden.

Wurde beim Vereinbaren mit @USE ein Einsprungpunkt festgelegt (@USE COMMAND= ...,ENTRY=entry,...), wird bei Eingabe der benutzerdefinierten Anweisung der gesamte Text hinter dem Benutzeranweisungssymbol an die Anweisungsroutine übergeben. Dieser Text kann von der Anweisungsroutine beliebig interpretiert werden.

Wurde beim Vereinbaren mit @USE kein Einsprungpunkt festgelegt (@USE COMMAND= ...,ENTRY=*,...), muss bei Eingabe der benutzerdefinierten Anweisung der Name des Einsprungpunktes (entry) angegeben werden. Dahinter kann eine Zeichenfolge angegeben werden, die der Anweisungsroutine übergeben wird.

spec entry [chars]

Dabei kann entry als Anweisungsname, chars als Operanden angesehen werden. Wurde das kompatible Format der @USE-Anweisung verwendet, werden maximal die ersten 8 Zeichen (in Großbuchstaben des Zeichensatzes EDF03IRV umgewandelt) der benutzerdefinierten Anweisung als Name des Einsprungpunktes betrachtet.

Wurde das neue Format verwendet, werden maximal die ersten 32 Zeichen (in Großbuchstaben des Zeichensatzes EDF03IRV umgewandelt) als Name des Einsprungpunktes betrachtet.

Einsprungpunkte, die auf diese Weise in der benutzerdefinierten Anweisung selbst angegeben werden, dürfen daher keine Kleinbuchstaben enthalten.

Es wird empfohlen, den Anweisungsnamen innerhalb derartiger benutzerdefinierter Anweisungen vom Rest der Anweisung durch ein Leerzeichen abzutrennen, um Fehlinterpretationen aufgrund des Abschneidens nach 8 bzw. 32 Zeichen auszuschließen.

Kann der an die Anweisungsroutine zu übergebende Text nicht in den Zeichensatz umgewandelt werden, der über die Initialisierungsroutine (siehe „Aufruf der Initialisierungsroutinezu einer benutzerdefinierten Anweisung“ (Aufruf der Initialisierungsroutine zu einer benutzerdefinierten Anweisung )) festgelegt wurde, wird die Anweisung mit einer Fehlermeldung abgewiesen.

Ist das Benutzeranweisungssymbol gleich dem aktuellen EDT-Anweisungssymbol, hat die EDT-Anweisung Vorrang. Das heißt, nur wenn keine EDT-Anweisung (in irgendeiner zulässigen Abkürzung) identifiziert werden kann, wird angenommen, es handle sich um eine Benutzeranweisung. Es liegt in der Verantwortung des Benutzers, Konflikte zu vermeiden.

Beim Sprung in die Anweisungsroutine sind die Register wie folgt geladen:

Register	Datenbereich
(R1) (R13) (R14) (R15)	A (PARAMETERLISTE) A (SAVEAREA) A (RETURN) V (ENTRY)

Erläuterung der Registerinhalte siehe in Abschnitt „Aufruf des EDT“).

Parameterliste    :     A (EDTGLCB, COMMAND)

Folgende Parameter werden vom EDT an die Anweisungsroutine übergeben:

• EDTGLCB
  Globaler EDT-Kontrollblock, wird vom EDT bereitgestellt und ist bereits initialisiert. Der Kontrollblock darf nach Verlassen der Anweisungsroutine nicht mehr verwendet werden.

  Welche Version des Kontrollblocks EDTGLCB verwendet wird, wurde über die Initialisierungsroutine (siehe Abschnitt „Aufruf der Initialisierungsroutine zu einer benutzerdefinierten Anweisung“) festgelegt. Im Feld EGLCDS übergibt der EDT die Taste mit der die Anweisung abgeschickt wurde (nur bei Anweisungsfiltern, siehe Abschnitt „Spezialanwendung als Anweisungsfilter“).

  Der Kontrollblock ist im Abschnitt „EDTGLCB - Globaler EDT - Kontrollblock“ beschrieben.

• COMMAND
  Vom EDT bereitgestellter Puffer, der die Zeichenfolge enthält, die bei der Eingabe der externen Anweisung angegeben wurde.

  Das Benutzeranweisungssymbol wird nicht übertragen. Die maximale Länge beträgt 32763 Byte + 4 Byte Längenfeld (siehe Abschnitt „Puffer“).

  Der Puffer COMMAND ist in dem Zeichensatz codiert, der über die Initialisierungsroutine (siehe Aufruf der Initialisierungsroutine zu einer benutzerdefinierten Anweisung) vereinbart wurde.

  Das Feld EGLCCSN wird vom EDT mit dem Namen des Zeichensatzes versorgt. In Abhängigkeit von der Einstellung bei @PAR LOW wird die Zeichenfolge vor Übergabe an die Anweisungsroutine ggf. in Großbuchstaben umgewandelt.

Hinweis

Die weitere Beschreibung bezieht sich auf einen Aufruf mit Version 2 des Kontrollblocks EDTGLCB. Die Beschreibung für den Aufruf mit Version 1 des Kontrollblocks findet sich in [3].

Eine Anweisungsroutine sollte immer die Version des erhaltenen Kontrollblocks EDTGLCB abfragen.

Übersichtstabelle

Die Anweisungsroutine wird vom EDT mit folgender Parameterliste aufgerufen:

Parameterliste    :     A (EDTGLCB, COMMAND)

Aufrufparameter		Rückkehrparameter
werden vom EDT vor Aufruf der externen Anweisungsroutine versorgt		werden vom EDT nach Rückkehr aus der externen Anweisungsroutine ausgewertet
EDTGLCB:	EGLUNIT EGLVERS EGLCCSN EGLCDS EGLUSR1 EGLUSR2	EDTGLCB:	EGLRETC EGLRMSG EGLCMDS EGLFILE EGLUSR2
COMMAND

Returncodes bei benutzerdefinierten Anweisungen

Die Returncodes werden von der Anweisungsroutine gesetzt und vom EDT ausgewertet. Hat die Anweisungsroutine im Feld EGLRMSG keinen Meldungstext abgelegt, werden vom EDT je nach Returncode folgende Meldungen ausgegeben:

EGLMRET	EGLSR1	Bedeutung
EUPRETOK EUPSYERR EUPRTERR	00 00 00	Keine Meldung Meldung EDT3991 Meldung EDT5991

Hat die Anweisungsroutine im Feld EGLRMSG eine eigene Meldung abgelegt, gibt der EDT diese Meldung anstelle der oben beschriebenen Meldungen aus (auch bei EUPRETOK).
Der Meldungstext der Anweisungsroutine wird dabei je nach Returncode in eine der EDT-Meldungen EDT0999, EDT3999 bzw. EDT5999 eingesetzt.

Bei anderen Returncodes gibt der EDT die Meldung EDT5410 aus. Die eigene Meldung im Feld EGLRMSG wird in diesem Fall nicht ausgegeben.

Normalerweise wird die Anweisungsroutine mit der aufrufenden Instanz des EDT kommunizieren wollen, d.h. sie benutzt den an der Schnittstelle übergebenen EDTGLCB für Aufrufe der EDT-Unterprogrammschnittstelle.

Dabei stehen der Anweisungsroutine zur Verarbeitung folgende Funktionen zur Verfügung:

• die Satzzugriffsfunktionen IEDTGET, IEDTPUT, usw. (siehe Abschnitt „LogischeSatzzugriffsfunktionen“).

• die Funktion IEDTEXE zum Ausführen einer EDT-Anweisung (siehe Abschnitt „IEDTEXE - Ausführen von EDT-Anweisungen ohne Bildschirmdialog“).

  Folgende Anweisungen dürfen bei IEDTEXE nicht angegeben werden:

  • eine weitere benutzerdefinierte Anweisung

  • der Aufruf einer Anwenderroutine (@RUN)

  • die Anweisungen @DIALOG, @EDIT, @END, @HALT, @MODE und @RETURN sowie

  • die Prozeduraufrufe @DO und @INPUT.

In Ausnahmefällen kann es auch gewünscht sein, dass die Anweisungsroutine mit einer andern Instanz des EDT kommuniziert. Dazu muss ein EDTGLCB benutzt werden, der unabhängig von dem mitgelieferten EDTGLCB initialisiert wurde oder noch gar nicht initialisiert ist. Da die beiden EDT-Instanzen vollkommen unabhängig voneinander laufen, bestehen für die Aufrufe an die andere Instanz keinerlei Einschränkungen. Es kann auf diesem Weg dann auch nicht auf die Daten der aufrufenden Instanz zugegriffen werden.