Wenn Sie den Event-Exit FORMAT verwenden, verzichten Sie auf die Ausgabeunterstützung der Systemkomponenten FHS und VTSU. Sie müssen dann Ihre eigene Formatierung schreiben und ggf. auch selbst für den Bildschirmwiederanlauf sorgen. openUTM erkennt den Event-Exit FORMAT am Präfix "-" des Formatkennzeichens in KCMF/kcfn.
Der Event-Exit FORMAT muss in der EXIT-Anweisung mit dem Operanden USAGE=FORMAT generiert werden. Es ist pro Anwendung nur ein Event-Exit FORMAT erlaubt. Teilformate können Sie nicht verwenden.
Der Event-Exit FORMAT kann in jeder von openUTM unterstützten Programmiersprache programmiert werden. Besonders geeignet sind die Programmiersprachen Assembler und C/C++. Die Beschreibung des FORMAT-Exits in diesem Abschnitt basiert auf der Programmiersprache Assembler - im Folgenden jedoch ein kurzes Beispiel für den Prototyp eines FORMAT-Exits in C:
void FORMATEX( struct kc_ca * const pKB
,char * const pSPAB
,char * const pFormatName
,char * const pDevice
,char * const pFormatArea
,char * const pPhysicallyInOutArea
,char * const pRestartArea
,char * const pFormatControlArea
,char * const pInOutIndicator
,char * const pSecondaryReturnCode
);
Adressleiste
openUTM stellt beim Aufruf des Event-Exits folgende Adressleiste zur Verfügung:
Reihenfolge der Wortadressen | Inhalt |
|---|---|
1. | Adresse des KB |
2. | Adresse des SPAB |
3. | Adresse des Formatnamens |
4. | Adresse des Terminaltyps |
5. | Adresse des Formatierungs-Benutzerbereichs |
6. | Adresse des physischen Ein-/Ausgabebereichs |
7. | Adresse eines Wiederanlaufbereichs |
8. | Adresse des Formatierungskontrollbereichs |
9. | Adresse des Ein-/Ausgabe-Indikators |
openUTM ruft die Formatierungsroutine auf, wenn man in den KDCS-Aufrufen MPUT, FPUT, DPUT, MGET oder FGET ein -Format verwendet.
Die Formatierung einer Dialog-Ausgabe-Nachricht (MPUT) erfolgt erst nach dem PEND- oder PGWT-Aufruf. Der Inhalt von KB und SPAB ist gleich dem des PEND- oder PGWT-Aufrufs. Die Formatierung einer asynchronen Ausgabenachricht erfolgt erst beim Senden. Der Inhalt von KB und SPAB ist in diesem Fall undefiniert, d.h. sie haben keinen Bezug mehr zum Teilprogramm, das den FPUT oder DPUT aufgerufen hat.
Die Formatierung einer Dialog-Eingabe-Nachricht erfolgt während der MGET-Behandlung. KB und SPAB haben den Inhalt vom MGET-Aufruf. Das gilt nur beim Event-Exit FORMAT, normalerweise formatiert openUTM vor dem INIT.
Die Formatierung einer asynchronen Eingabenachricht erfolgt beim Empfang der Nachricht, nicht erst beim FGET. Die Inhalte von KB und SPAB sind daher undefiniert.
Es ist darauf zu achten, dass vor dem Transaktionscode kein Feld sein darf, da openUTM den TAC ermittelt, ohne den Formatexit aufzurufen.
Formatname (Adresse in Wort 3)
bei Eingabeformatierung der Formatname, der bei der vorausgehenden Ausgabeformatierung für dieses Terminal benutzt wurde (Aufrufe: MPUT, FPUT, DPUT oder Kommando KDCFOR).
bei Ausgabeformatierung die Angabe in KCMF/kcfn des Parameterbereichs des MPUT- bzw. FPUT-Aufrufs.
Terminaltyp und Zusatzinformationen (Adresse in Wort 4)
t | ist der physische Gerätetyp, wie er beim TSTAT-Makro mit TCHAR abgefragt werden kann. Die Codes lassen sich dem DCSTA-Makro entnehmen (siehe BS2000-Handbuch „Makroaufrufe an den Ablaufteil“). |
Wenn der Terminaltyp vom Event-Exit FORMAT nicht unterstützt wird, muss ein Formatierungsfehler erzeugt werden. | |
z | ist eine Zusatzinformation: |
X’00’ = Bildschirm löschen; | |
X’01’ = Bildschirm nicht löschen | |
ba | ist die Bildschirmausgabefunktion: |
X’0001’: KCRESTRT | |
X’0001’: KCREPL | |
X’0002’: KCERAS | |
X’0004’: KCALARM | |
X’0008’: KCREPR | |
X’2000’: KCEXTEND | |
X’4000’: KCCARD | |
qa | ist ein Kennzeichen, das anzeigt, ob eine Quittung angefordert werden muss - gilt nur für Ausgaben auf Drucker. |
X’00’ = Quittung nicht anfordern | |
X’01’ = Quittung anfordern | |
q1,q2 | Ist qa = X’01’, stehen in diesen beiden Bytes die Quittungs-Nummern im EBCDIC-Code. |
dc | device characteristica; enthält in der Länge von 8 Byte Informationen über Gerätetyp und -ausbau, so wie dies im PDN mit XSTAT und XOPCH generiert wurde. |
Formatierungs-Benutzerbereich (Adresse in Wort 5)
Eingabeformatierung:
Nach dem Aufruf des Formatexits erwartet openUTM hier die logische Nachricht im Eingabeformat (siehe „Nachrichtenformate"). Die maximale Länge wird bestimmt durch den generierten Wert (siehe MAX-Anweisung, Operand NB im openUTM-Handbuch „Anwendungen generieren“). Diese maximale Länge trägt openUTM vor dem Aufruf in das Längenfeld des Formatierungs-Benutzerbereichs ein.
Falls die Umsetzung der logischen in die physische Nachricht die Bereichslänge überschreitet, muss ein Formatierungsfehler erzeugt werden.
Ausgabeformatierung:
Der Bereich enthält die zu formatierende Nachricht, wie sie beim MPUT bzw. FPUT im Nachrichtenbereich bereitgestellt wurde. Die Nachricht ist im Eingabeformat (siehe „Nachrichtenformate") aufgebaut. Teilformate sind nicht erlaubt.
Physischer Ein-Ausgabebereich (Adresse in Wort 6)
Eingabeformatierung:
openUTM übergibt die Nachricht, wie sie vom Terminal kommt, im Eingabeformat.
Ausgabeformatierung:
Nach dem Aufruf des Formatexits erwartet openUTM hier die formatierte Nachricht im Ausgabeformat.
Die maximale Länge ist bestimmt durch die maximal auf der Verbindung zum Client erlaubten Nachrichtenlänge. Diese maximale Länge trägt openUTM vor dem Aufruf in das Längenfeld des physischen Ein-/Ausgabebereiches ein.
Falls bei der Umsetzung der logischen in die physische Nachricht die Bereichslänge überschritten wird, muss ein Formatierungsfehler oder eine Ersatznachricht erzeugt werden.
Wiederanlaufbereich (Adresse in Wort 7)
Den Wiederanlaufbereich muss man benutzen, um Bildschirmformate bei Bedarf rekonstruieren zu können, was z.B. in folgenden Situationen vorkommen kann:
Beim KDCDISP-Kommando (Anzeigen des letzten Bildschirms)
Wenn der Terminalbenutzer einen unterbrochenen Vorgang mit seinem zuletzt eingegebenen Format fortsetzen möchte (z.B. nach einem Verbindungsverlust oder Eingabe des Kommandos KDCOFF innerhalb eines laufenden Vorgangs)
Wenn der Bildschirm durch eine asynchrone Ausgabe zerstört wurde und wiederhergestellt werden soll.
Man muss dafür sorgen, dass der Wiederanlaufbereich immer die aktuelle logische Nachricht enthält, die bei Bedarf ausgegeben werden soll.
Will man bei einer Ausgabeformatierung zuerst den alten Bildschirm löschen, muss man den Wiederanlaufbereich neu aufbauen.
Soll bei einer Ausgabe der alte Bildschirm nicht gelöscht werden, braucht man im Wiederanlaufbereich nur die Felder zu ändern (überschreiben), die auch am Terminal modifiziert werden.
Nach Eingaben vom Terminal muss man den Wiederanlaufbereich entsprechend aktualisieren.
Er wird beim PEND in der Länge gesichert, die für den Benutzerbereich für dieses Format bei der letzten Ausgabeformatierung angegeben wurde (KCLM bei MPUT).
Beim Wiederanlauf wird eine Ausgabeformatierung durchgeführt. Dabei ist die Adresse des Formatierungsbenutzerbereichs gleich der Adresse des Wiederanlaufbereichs (d.h. es gibt nur den Wiederanlaufbereich).
Formatierungs-Kontrollbereich (Adresse in Wort 8)
Ab Adresse + 1 dieses Bereichs müssen Sie im Event-Exit FORMAT den Rückkehrcode (sedezimal) ablegen, der aussagt, ob die Formatierung erfolgreich war.
Als Eintrag kommt infrage:
X’00’ | Die Ausgabeformatierung war erfolgreich. |
X’xy’ | Fehlermeldungen des Benutzers, die als UTM-Rückgabecode "FRxy" im Feld KCRCDC weitergegeben werden (Formatierungsfehler). Verboten sind die Einträge X’01’, X’02’, X’03’, X’04’, X’08’, X’10’ und X’99’, weil diese Rückkehrcodes für die Zusammenarbeit von openUTM und FHS reserviert sind. |
Ein-Ausgabe-Indikator (Adresse in Wort 9)
Das erste Byte des Indikators enthält den Wert:
| X'00': | für Eingabeformatierung |
| X'01': | für Ausgabeformatierung |
| X'02': | für Restart |
| X'03': | bei KDCFOR |
Im Restart-Fall sind die Adressen des Formatierungs- und Wiederanlaufbereichs identisch.
Nachrichtenformate
Im Event-Exit FORMAT werden zwei unterschiedliche Nachrichtenformate verwendet (siehe vorigen Abschnitt). Diese sind nicht unbedingt auf Halbwortgrenze ausgerichtet.
Eingabeformat -------------------------------------------
| länge | b | b | (Teil-)Nachricht |
-------------------------------------------
0 2 4
Ausgabeformat --------------------------------------------------
| länge | b | b | b | (Teil-)Nachricht |
--------------------------------------------------
0 2 5
länge | ist die Länge der Gesamtnachricht (binär), inklusive des Nachrichtenvorspanns, der bei der Eingabeformatierung 4 Bytes und bei der Ausgabeformatierung 5 Bytes beträgt. |
b | ist ein Leerzeichen (X’40’) |
Informationen über den Nachrichtenaufbau von physischen Nachrichten finden Sie in den Handbüchern zu Ihrem Terminal.
FEXIT CSECT
STM 14,12,12(13)
BALR 12,0
USING *,12
USING KB,2
USING SPAB,3
USING DFORMNAM,4
USING DFORMSDE,5
USING DADUSERA,6
USING DAREAFMI,7
USING DADRSRTA,8
USING DMDCBUSE,9
USING DFORMMOD,10
LM 2,10,0(1)
*
* EIN- ODER AUSGABEFORMATIERUNG, RESTART ODER KDCFOR ?
*
CLI FORM#IND,X'00' 00=EINGABE, 01=AUSGABE
BE EINFORM 02=RESTART, 03=KDCFOR
CLI FORM#IND,X'01'
BE AUSFORM
CLI FORM#IND,X'02'
BE RESTFORM
CLI FORM#IND,X'03'
BE FORFORM
*
* SETZEN FORMATIERUNGSFEHLER: KEIN GUELTIGER OPCODE !
*
********************************************************* K D C F O R
*
FORFORM DS 0H
*
* A) PHYS. NACHR. LT. FORMATNAME AUFBAUEN
* UND MIT "STD."-WERTEN VORBESETZEN
* B) QUITT.-ANFORDERUNG ('FORMQA') AUSWERTEN
* UND NACHRICHTENKOPF VERSORGEN
* C) RESTART-BER. AUFBAUEN
* D) RET.-CODE IM FORMAT.-KONTROLLBER. SETZEN
*
END#EXIT LM 14,12,12(13)
BR 14
*
*********************************************** EINGABE-FORMATIERUNG
*
EINFORM CNOP 0,4
*
* A) PHYS. NACHRICHT LT. FORMATNAME AUSWERTEN UND
* FORMAT.-BENUTZERBER. ('DADUSERA') AUFBAUEN GEM.
* NACHRICHTENFORMAT F. EINGABE
* B) RESTART-BER. VERSORGEN
* C) RET.-CODE IM FORMAT.-KOMTROLLBER. SETZEN
*
B END#EXIT
EJECT
************************************************ AUSGABE-FORMATIERUNG
*
AUSFORM CNOP 0,4
*
* A) AUFBAUEN DER PHYS. NACHRICHT,
* DABEI WIRD AUSGEWERTET:
* - FORMAT.-BENUTZERBER.
* - FORMAT-NAME
* - STATIONSTYP UND ZUSATZINFORMATION
* MIT
* 1) 'FORMCLMO' (BILDSCHIRM LOESCHEN ?
* D.H. "FORMAT-ALT" = "FORMAT-NEU" ?)
* 2) 'FORMBA' (BILDSCHIRMAUSGABE-FUNKTION)
* 3) 'FORMQA' UND GGF. 'FORMRB'
* B) RESTARTBEREICH VERSORGEN
* C) RET.-CODE IM FORMAT.-KONTROLLBER. SETZEN
*
B END#EXIT
***************************************************** R E S T A R T
*
RESTFORM CNOP 0,4
*
* A) WIEDERANLAUF-BER. AUSWERTEN
* UND PHYS. NACHRICHT AUFBAUEN
* B) RET.-CODE IN FORMAT.-KONTROLLBER. SETZEN
*
B END#EXIT
*
EJECT
*
* DSECTS FUER PARAMETERUEBERGABE VON UTM
* >>>>>>>>>>>>>>>>>> NICHT VOLLSTAENDIG DEFINIERT
*
KB KCKBA D
*
SPACE 5
SPAB KCPAA D
*
EJECT
DFORMNAM DSECT
FORMNAME DS CL8
*
DFORMSDE DSECT
FORMSDEV DS C
FORMCLMO DS C
FORMBA DS CL2
FORMQA DS C
FORMRB DS CL2
*
DADUSERA DSECT
DS 0H
*
DAREAFMI DSECT
DS 0H
*
DADRSRTA DSECT
DS 0H
*
DMDCBUSE DSECT
DS 0H
*
DFORMMOD DSECT
FORM#IND DS X
END