IEDTCMD - Ausführen von EDT-Anweisungen

Bei diesem Aufruf wird dem EDT eine Anweisung bzw. Anweisungsfolge zur Ausführung übergeben.
Ist das Anweisungsfeld leer (Länge 4), wird sofort zum rufenden Programm zurückgekehrt.

Folgende Anweisungen sind an der IEDTCMD-Schnittstelle erlaubt:

Außerdem sind die benutzerdefinierten Anweisungen erlaubt (siehe Kapitel „Benutzerdefinierte Anweisungen - @USE“).

Die Anweisung @EDIT (mit Ausnahme des Formats 4 - @EDIT LONG...) wird an der IEDTCMD-Schnittstelle grundsätzlich als @EDIT ONLY interpretiert und bewirkt den Übergang in den Line-Modus-Dialog.

Das EDT-Anweisungssymbol muß nicht angegeben werden (außer bei @:).

Der Programmlauf (Initialisierung, Übergang zum Benutzerdialog, Beendigung mit Entladen und Speicherfreigabe) wird durch die Anweisungsfolge gesteuert, die an den EDT übergeben wird.

Nach dem Laden von EDT wird dessen Datenbereich initialisiert (nur beim 1.Aufruf).

Nach dem Ausführen der Anweisungsfolge kehrt der EDT zum rufenden Programm zurück.

@HALT in der übergebenen Anweisungsfolge bewirkt das Beenden des EDT (Speicherfreigabe und Entladen).

Ist die Anweisungsfolge nicht mit @HALT abgeschlossen, wird ohne Freigabe des Datenbereichs zum rufenden Programm zurückgekehrt. Durch einen erneuten Aufruf mit einer Anweisungsfolge kann die Verarbeitung fortgesetzt oder durch Übergabe von @HALT der EDT beendet werden.

Innerhalb einer Routine, die eine benutzerdefinierte Anweisung bearbeitet, bzw. innerhalb einer Anwenderroutine (siehe Kapitel „Benutzerdefinierte Anweisungen - @USE“ und „Anwenderroutinen - @RUN“) ist ein Aufruf der IEDTCMD- Schnittstelle nur dann zulässig, wenn er benutzt wird, eine andere als die aufrufende Instanz des EDT anzusprechen.

Anweisungen an die aufrufende EDT-Instanz, bei denen der an die Anweisungsroutine übergebene globale Kontrollblock EDTGLCB verwendet wird, dürfen nur über die IEDTEXE- Schnittstelle erfolgen. Ein Aufruf der IEDTCMD -Schnittstelle aus einer Anweisungsroutine mit dem EDTGLCB der aufrufenden Instanz wird mit dem Returncode EUPPAERR/EUPPA08 abgewiesen. Weitere Informationen dazu finden sich im Kapitel „BenutzerdefinierteAnweisungen - @USE“  und den folgenden.

Tritt ein Fehler auf (Syntax- oder Laufzeitfehler), wird die Abarbeitung sofort mit einem entsprechenden Returncode und einer Fehlermeldung unterbrochen. In diesen Fällen dient das Feld EGLCMDS (in EDTGLCB) als Fehlerzeiger. Dieser zeigt auf den Beginn der fehlerhaften Anweisung innerhalb der Anweisungsfolge. Aus Kompatibilitätsgründen wird das erste Zeichen nach dem Satzlängenfeld mit '1' nummeriert (das erste Zeichen der übergebenen Anweisungsfolge hat bei dieser Zählung die Nummer '3'). Die Zählung erfolgt grundsätzlich in Zeichen, nicht in Bytes. Es wird der Returncode EUPSYERR bzw. EUPRTERR übergeben.

Benutzerdialog

Der Wechsel zum Benutzerdialog kann durch die Anweisung @DIALOG (Bildschirmdialog) bzw. durch @EDIT ONLY (Line-Modus-Dialog) innerhalb der übergebenen Anweisungsfolge erfolgen.

Jedes Mal, wenn mit der Anweisung @DIALOG aus der übergebenen Anweisungsfolge heraus in den Bildschirmdialog gewechselt wird, werden die übergebenen Meldungen (MESSAGE1, MESSAGE2) in den Meldungszeilen angezeigt.

Mit @EDIT ONLY wird in den Line-Modus-Dialog (Lesen mit RDATA) umgeschaltet.

Der Benutzerdialog wird mit @END, @HALT oder @RETURN beendet, im F-Modus auch mit [K1].

Der EDT übergibt einen Returncode an den globalen Kontrollblock EDTGLCB (EGLRETC). Nach Beenden des Benutzerdialogs wird die Abarbeitung der Anweisungsfolge fortgesetzt. Die Anweisung @END setzt den gleichen Returncode wie @HALT.

Bei @HALT und @RETURN mit der Angabe von <message> wird der Text zusätzlich im Meldungsfeld EGLRMSGF im Kontrollblock EDTGLCB hinterlegt.

Wenn der Dialog mit @HALT ABNORMAL beendet wurde, wird der Mainreturncode EUPABERR gesetzt.

Ist das Flag EUPNTXT im EDTUPCB gesetzt, wird die Angabe von message bzw. ABNORMAL mit Fehlermeldung (im Dialog) zurückgewiesen.

Das Flag EGLSTXIT im EDTGLCB wird bei jedem Aufruf über die IEDTCMD-Schnittstelle ausgewertet. Bei Rückkehr zum aufrufenden Programm werden die Unterbrechungsroutinen des EDT - falls sie angefordert wurden - wieder abgemeldet.

Durch Setzen des Flags EUPNUSER im EDTUPCB wird die Verarbeitung einer @USE-Anweisung im Dialog abgewiesen.

Kontrollstrukturen

Folgende Datenbereiche müssen vor dem Aufruf der Funktion definiert werden:

• der Kontrollblock EDTGLCB

• der Kontrollblock EDTUPCB

• die Anweisungsfolge (COMMAND)

• optional 2 Meldungszeilen (MESSAGE1 und MESSAGE2), sonst Nullzeiger

Die Kontrollblöcke sind im Abschnitt „Generierung und Aufbau der Kontrollblöcke“. Die Puffer COMMAND, MESSAGE1 und MESSAGE2 sind im Abschnitt Puffer beschrieben.

Bei ungeteiltem Bildschirm wird im Dialog MESSAGE1 in der Meldungszeile angezeigt- bei geteiltem Bildschirm wird MESSAGE1 in der ersten, MESSAGE2 in der zweiten Meldungszeile angezeigt.

Enthält das Längenfeld von MESSAGE1 oder MESSAGE2 einen Wert, der kleiner oder gleich 4 ist, wird die Ausgabe der entsprechenden Meldungszeile unterdrückt. Beim erstmaligen Übergang in den benutzerdialog wird in diesem Fall die EDT-Startmeldung ausgegeben. Dies gilt sinngemäß auch bei Angabe eines Nullzeigers.

Wenn @DIALOG bzw. @EDIT ONLY nicht als letzte Anweisung in der Anweisungsfolge steht, ist zu beachten, dass Returncode und Meldung im EDTGLCB von nachfolgenden Anweisungen verursacht werden können.

Aufruf

Folgende Angaben sind notwendig (siehe Übersichtstabelle):

• Versorgen der benötigten Felder in den Kontrollblöcken EDTGLCB und EDTUPCB.

• Versorgen des Puffers COMMAND mit der Anweisungsfolge.

• Versorgen der Puffer MESSAGE1 und MESSAGE2 mit Meldungstexten bzw. der entsprechenden Felder der Parameterliste mit Nullzeigern.

• Aufruf der Einsprungadresse IEDTCMD mit der Parameterliste.

Übersichtstabelle

(Kontrollblöcke siehe Abschnitt „EDTGLCB - Globaler EDT - Kontrollblock“).

Einsprungadresse    :     IEDTCMD

Parameterliste      :     A (EDTGLCB, EDTUPCB, COMMAND,

   MESSAGE1, MESSAGE2)

Aufrufparameter		Rückkehrparameter
EDTGLCB:	EGLUNIT EGLVERS EGLINDB EGLCCSN	EDTGLCB:	EGLRETC EGLRMSG EGLCMDS EGLFILE
EDTUPCB:	EUPUNIT EUPVERS EUPINHBT
COMMAND MESSAGE1 / NULL MESSAGE2 / NULL

Hinweis
Bei jeder Rückkehr werden im Kontrollblock EDTGLCB der Returncode und der Name der aktuellen Arbeitsdatei (EGLFILE) eingetragen.

Returncodes

EGLMRET	EGLRS1
EUPRETOK	EUPOK00 EUPOK04 EUPOK08 EUPOK12 EUPOK16 EUPOK20
EUPSYERR EUPRTERR EUPEDERR EUPOSERR EUPUSERR EUPPAERR	00 00 00 00 00 EUPPA04 EUPPA08 EUPPA12 EUPPA16 EUPPA20 EUPPA24
EUPSPERR EUPABERR	00 EUPOK08

EGLMRET und EGLRS1 sind Felder des Kontrollblocks EDTGLCB. Die Bedeutung der Returncodes ist im Abschnitt „EDTGLCB - Globaler EDT - Kontrollblock“ beschrieben.

Beispiel

*****************************************************************
* CMDBSP:  BEISPIEL FUER AUSFUEHREN EINER EDT-ANWEISUNGSFOLGE   *
*          IM UNICODE-MODUS                                     *
*          (PAR SPLIT=OFF,LOWER=ON,SCALE=ON,INDEX=ON;DIALOG)    *
*****************************************************************
*
CMDBSP   START
CMDBSP   AMODE ANY
CMDBSP   RMODE ANY
         BALR  R10,0
         USING *,R10
         MVC   EGLCCSN,CCSN041
         LA    R13,SAVEAREA
         LA    R1,CMDPL
         L     R15,=V(IEDTCMD)

         BALR  R14,R15
         TERM  ,
*
* DATENBEREICH
R1       EQU   1
R10      EQU   10
R13      EQU   13
R14      EQU   14
R15      EQU   15
*
SAVEAREA DS    18F
* - KONTROLLBLOECKE (EDTGLCB, EDTUPCB)
         IEDTGLCB C,VERSION=2
         IEDTUPCB C,VERSION=3
* - ANWEISUNGSFOLGE (COMMAND)
CMDDIA   DC    Y(CMDDIAL)
         DC    CL2' '
         DC    C'PAR SPLIT=OFF,LOWER=ON,SCALE=ON,INDEX=ON;DIALOG'
CMDDIAL  EQU   *-CMDDIA
* - MELDUNGSZEILE (MESSAGE1)
MSG1DIA  DC    Y(MSG1DIAL)
         DC    CL2' '
         DC    C'DIALOGENDE MIT HALT ODER <K1>'
MSG1DIAL EQU   *-MSG1DIA
* - MELDUNGSZEILE (MESSAGE2)
MSG2DIA  DC    Y(MSG2DIAL)
         DC    CL2' '
MSG2DIAL EQU   *-MSG2DIA
* - PARAMETERLISTE FUER CMD
CMDPL    DC    A(EDTGLCB)
         DC    A(EDTUPCB)
         DC    A(CMDDIA)
         DC    A(MSG1DIA)
         DC    A(MSG2DIA)
*
CCSN041  DC    CL8’EDF041 ’
*
         END   CMDBSP

Aufruf im C-Programm

Benötigte Include-Dateien:

#include <stdio.h>

#include <iedtgle.h>

Die Kontrollblöcke EDTGLCB und EDTUPCB werden folgendermaßen deklariert und initialisiert:

iedglcb glcb = IEDGLCB_INIT;

iedupcb upcb = IEDUPCB_INIT;

Für den Aufbau und die Versorgung der Strukturen command, message1 und message2 findet sich ein Beispiel im Abschnitt „Beispiel 1 - C-Hauptprogramm“.

Aufgerufen wird die Funktion IEDTCMD mit den Adressen dieser Strukturen:

IEDTCMD(&glcb,&upcb,&command,&message1,&message2);