Der DCAM-Exit bietet dem Benutzer die Möglichkeit, DCAM-Funktionen zu erweitern, zu ändern und eigene spezielle Funktionen hinzuzufügen. Solche Funktionen sind z.B.:
über TRANSDATA hinausgehender Datenschutz durch erweiterte Berechtigungsprüfungen, z.B. Öffnen von Anwendungen abhängig machen von der Benutzerkennung: Verbindungsaufbau für eine Anwendung nur mit definierten Partnern/Prozessoren zulassen
zusätzliche Aktionen veranlassen, z.B. Jobs starten, Meldungen ausgeben
Die benutzerspezifische Exit-Routine wird beim Öffnen und Schließen von Anwendungen sowie beim Öffnen und Schließen von Verbindungen aufgerufen. Beim Öffnen von Anwendungen und Verbindungen kann die Exit-Routine den Aufruf annehmen, ablehnen oder ggfs. modifizieren. Die Aufrufe beim Schließen dienen nur zur Information der Exit-Routine.
Aufrufereignisse
Zurzeit gibt es 12 Aufrufereignisse für die DCAM-Exit-Routine. Zu unterscheiden sind Hauptereignisse (Exit Maincases) und Nebenereignisse (Exit Subcases), die jeweils durch eine 3 Zeichen lange Buchstabenfolge gekennzeichnet sind. Die 6-stellige Kombination aus Haupt- und Nebenereignis-Kennzeichnung bezeichnet eindeutig das Aufrufereignis.
Auf den folgenden Seiten sind die Hauptereignisse APP und CON und ihre Nebenereignisse einander gegenübergestellt.
Hauptereignis APP
APP betrifft Ereignisse, die mit dem Öffnen und Schließen von Anwendungen (Application) zusammenhängen.
Exit Subcase | Aufruf der Exit-Routine | Funktion der Exit-Routine |
APPOPN | bei jedem YOPEN-Aufruf: |
|
APPCLS | bei jedem YCLOSE-Aufruf: |
|
APPSHU | bei jedem internen Schließen einer Anwendung, | |
APPRTM | beim internen Schließen einer Anwendung, | Ersatztask starten |
APPFCL | bei unvorhergesehenem Schließen einer Anwendung wegen einer DCAM-Störung |
*) | Der Exit wird nur beim Schließen, nicht bei einer eventuell vorangehenden Warnung aufgerufen. Er wird nicht aufgerufen, wenn vor der DCAM-Terminierung die TIAM-Terminierung abläuft, d.h. wenn das DCAM-Programm als Dialogtask gestartet wurde. In diesem Fall wird bereits durch TIAM eine Task-Terminierung eingeleitet, d.h. der Exit APPTRM wird aufgerufen. |
Hauptereignis CON
CON betrifft Ereignisse, die mit dem Auf-/Abbau von Verbindungen zusammenhängen. Die Exit-Routine wird jedoch nicht aufgerufen, wenn beim Schließen einer Anwendung implizit alle noch bestehenden Verbindungen geschlossen werden.
Folgende Nebenereignisse sind zu unterscheiden:
Auffordern zum Verbindungsaufbau (YOPNCON ACQUIRE):
beim YOPNCON-ACQUIRE-Aufruf des Benutzers
nach erfolgreichem Verbindungsaufbau
Annehmen einer Verbindungsaufforderung
beim Eintreffen einer Aufforderung zum Verbindungsaufbau
nach Annahme der Aufforderung (YOPNCON ACCEPT)
bei explizitem Verbindungsabbau oder nach einem DCAM-Fehler:
Verbindungsabbau durch den Benutzer
Erzwungener Verbindungsabbau durch Störung
Verbindungsabbau durch den Partner
Exit Subcase
Aufruf der Exit-Routine
Funktion der Exit-Routine
CONACQ
bei Senden einer Aufforderung zum Verbindungsaufbau (YOPNCON ACQUIRE),
nach Prüfung der Benutzerangaben
vor Bearbeitung des Aufrufs (d.h. vor BCAM-Call ' REQCON' )zusätzliche Prüfungen z.B. Verbindungsnachricht (LOGON MESSAGE) gemäß Vereinbarungen?
Aufruf annehmen
Aufruf ablehnen
YOPNCON-Parameter ändern
CONACC
bei jedem Annehmen eines Verbindungswunsches (YOPNCON ACCEPT),
nach Prüfung der Benutzerangaben,
vor Bearbeitung des Aufrufszusätzliche Prüfungen
Auftrag annehmen
Auftrag ablehnen
YOPNCON-Parameter ändern
CONCPL
nach erfolgreichem Verbindungsaufbau,
d.h., wenn ein YOPNCON ACQUIRE vom Partner angenommen wurdeCONREQ
beim Eintreffen eines Verbindungswunsches,
nach Prüfung der Angaben,
vor Bearbeitung des Verbindungswunscheszusätzliche Prüfungen
Verbindungswunsch
annehmen / ablehnen
CONCLS
bei jedem Verbindungsabbau durch den Benutzer (YCLSCON),
vor Freigabe der DCAM-DatenstrukturCONFCL
bei jedem erzwungenen Verbindungsabbau wegen NEA-Protokollfehler oder wegen Quittungsüberlauf
CONBAD
bei jedem Verbindungsabbau durch den Partner
Folgende Informationen werden an die Exit-Routine übergeben:
R1 = A(YDDEXPL) = DCAM-Exit-Parameterbereich R12 = A(TPR Program Manager) R13 = A(Sicherungsbereich) R14 = A(indirekter Rücksprung) R15 = A(Exit-Routine)
Rückkehrinformation an die rufende Systemkomponente erfolgt über den Parameterbereich im Feld YDDXRETC:
|
| |
|
| |
|
| |
| ||
| ||
| ||
Das Feld FDBK muss versorgt werden, wenn RC=04 gesetzt ist. Die Angabe wird an den DCAM-Benutzer im Feld FDBK1/FDBK2 (siehe Handbuch „DCAM-Makroaufrufe“ [1]) übergeben. FDBK kann entweder aus einem für die Exit-Routine reservierten Bereich 'CC00'-'CCFF' genommen werden oder kann einer der gültigen DCAM-Returncodes sein (siehe Handbuch „Systemmeldungen“ [15]). FDBK darf nicht '0000' sein. Ist RC = 08, übergibt die Exit-Routine im Parameterbereich YDDEXPL die gültigen Daten für die Modifikation. Die Hinweise zur Programmierung von Exit-Routinen sind zu beachten.
Das Feld FDBK wird nur bei den Exitereignissen APPOPN, CONACQ und CONACC an den Benutzer übergeben (entspricht YOPEN, YOPNCON ACQ und YOPNCON ACC), jedoch nicht an den Partner geschickt.
Bei Ablehnung eines Verbindungswunsches durch den Systemexit des Partners wird der YOPNCON ACQUIRE nicht mit dem dort angegebenen FDBK sondern mit X'0C40' beendet.
DSECT
YDDEXPL D
YDDEXPL DSECT
*******************************************************************
* *
* DCAM EXIT PARAMETERLISTE *
* *
*******************************************************************
*
* EINGABEPARAMETER
*
YDDXDPAR DS A A(DARPPAR)
* DCAM INTERNER ARBEITSBEREICH
YDDXMAIN DS X EXIT-MAIN-CASE
YDDXAPPL EQU 1 APPL
YDDXCONN EQU 2 CONN
YDDXSUB DS X EXIT-SUB-CASE
YDDXAOPN EQU 1 APPOPN
YDDXACLS EQU 2 APPCLS
YDDXASHU EQU 3 APPSHU
YDDXATRM EQU 4 APPTRM
YDDXAFCL EQU 5 APPFCL
YDDXCACQ EQU 6 CONACQ
YDDXCACC EQU 7 CONACC
YDDXCCPL EQU 8 CONCPL
YDDXCREQ EQU 9 CONREQ
YDDXCCLS EQU 10 CONCLS
YDDXCFCL EQU 11 CONFCL
YDDXCBAD EQU 12 CONBAD
*
* EINGABE-/RUECKGABEPARAMETER
*
YDDXLOGL DS H LAENGE DER LOGON MESSAGE
YDDXLOGM DS CL80 LOGON MESSAGE
*
* RUECKGABEPARAMETER
*
YDDXPW DS XL4 PASSWORT
YDDXRETC DS F RETURNCODE '..FDBKRC'
*
YDDXL EQU *-YDDEXPL LAENGE DER DCAM EXIT PARAMETERLISTE
*,YDDEXPL 060 950330 55647211
YDDXDPAR | A(DARPPAR) | |
Adresse eines DCAM-internen Arbeitsbereichs, in dem weitere aufrufspezifische Informationen an die Exit-Routine übergeben werden | ||
YDDXMAIN | Indikator für das Hauptereignis | |
YDDXMAIN | Indikator für das Hauptereignis | |
YDDXAPPL | Hauptereignis ' APP' (betr. Anwendungen) | |
YDDXCONN | Hauptereignis ' CON' (betr. Verbindungen | |
YDDXSUB | Indikator für das Nebenereignis | |
YDDXAOPN | Exit-Case APPOPN | |
YDDXACLS | Exit-Case APPCLS | |
YDDXASHU | Exit-Case APPSHU | |
YDDXATRM | Exit-Case APPTRM | |
YDDXAFCL | Exit-Case APPFCL | |
YDDXCACQ | Exit-Case CONACQ | |
YDDXCACC | Exit-Case CONACC | |
YDDXCCPL | Exit-Case CONCPL | |
YDDXCREQ | Exit-Case CONREQ | |
YDDXCCLS | Exit-Case CONCLS | |
YDDXCFCL | Exit-Case CONFCL | |
YDDXCBAD | Exit-Case CONBAD | |
YDDXLOGL | Länge der Verbindungsnachricht (LOGON-Message) im Feld YDDXLOGLM; die Verbindungsnachricht darf höchstens 80 Bytes lang sein. Dieses Feld kann von der Exit-Routine verändert werden. | |
YDDXLOGM | enthält die Verbindungsnachricht (LOGON-Message), die von der Exit-Routine verändert werden kann. | |
YDDXPW | enthält ein Kennwort, das die Exit-Routine beim Rücksprung an DCAM übergibt. Dieses Kennwort ersetzt das vom Benutzer angegebene RDF-Kennwort beim YOPEN oder das LOGON-Kennwort beim YOPNCON ACQUIRE. | |
YDDXRETC | Returncode der Exit-Routine | |
Hinweise zur Programmierung von DCAM-Exit-Routinen
Zusätzlich zu den in „Exit-Routinen“ beschriebenen Regeln gelten für DCAM-Exit-Routinen folgende Einschränkungen
Auf alle Felder der DCAM-Datenstruktur (DARPPAR, Kontrollblöcke, s.u.) darf nur lesend zugegriffen werden. Schreibzugriff ist nur für die Rückgabefelder im Parameterbereich YDDEXPL erlaubt.
Es sind keine BCAM-Aufrufe erlaubt.
Die Exit-Routine darf keine Börsen-Locks setzen.
Die Exit-Routine darf ihren Prozess(PCB)-Level nicht ändern.
Auszug aus der DCAM-Datenstruktur
Die für die Programmierung von Exit-Routinen wichtigsten Elemente der DCAM-Datenstruktur sind nachfolgend aufgeführt. Da für das Layout der DCAM-Kontrollblöcke keine Kompatibilität garantiert wird, darf der Zugriff zur DCAM-Datenstruktur nur über die symbolischen Adressen erfolgen. Bei DCAM-Versionswechsel können Neuübersetzungen oder Sourceänderungen notwendig werden.
DCAM-interner Arbeitsbereich
DARPPAR
enthält taskspezifische Daten, z.B. die aktuellen Adressen der DCAM-Kontrollblöcke (siehe Handbuch „DCAM Makroaufrufe“ [1])
Eine DSECT für DARPPAR kann erzeugt werden mit dem Makroaufruf
[name] YDDDVEC D [,prefix]
Standardwerte: | name | YDDDVEC |
prefix | YDDV |
DCAM Application Control Block
DACB
enthält anwendungsspezifische Daten, z.B. Anwendungsname, Attribute ... Der DACB wird beim YOPEN angelegt und bleibt bis zum Schließen der Anwendung bestehen.
Eine DSECT kann erzeugt werden mit dem Makroaufruf
[name] YDDDACB D [,prefix]
Standardwerte: | name | YDDDACB |
prefix | YDDH |
DCAM Connection Control Block
DCCB
enthält verbindungsspezifische Daten, z.B. Partner-, Prozessornamen. Pro Verbindung wird ein DCCB angelegt.
Eine DSECT kann generiert werden mit dem Makroaufruf
[name] YDDDCCB D [,prefix]
Standardwerte: | name | YDDDCCB |
prefix | YDDL |
DCAM Request Parameter Block
DRPB
enthält bei asynchronen Aufrufen die aufrufspezifischen Informationen aus dem RPB.
Eine DSECT kann erzeugt werden mit dem Makroaufruf
[name] YDDDRPB D [,prefix]
Standardwerte: | name | YDDDRPB |
prefix | YDDD |
Feldinhalte bei Aufruf der Exit-Routine
Abhängig vom Aufrufereignis (Exit Case) werden die in den folgenden Tabellen enthaltenen Felder des Exit-Parameterbereichs und des internen Arbeitsbereiches versorgt. Nicht versorgte Felder und Adressen werden mit X'00' vordefiniert.
YDDEXPL - Exit-Parameterbereich
Feldname | Feldinhalt | Exit Case | |||||||||||
APP | CON | ||||||||||||
OPN | CLS | SHU | TRM | FCL | ACQ | ACC | CPL | REQ | CLS | FCL | BAD | ||
YDDXMAIN | Exit Main Case | x | x | x | x | x | x | x | x | x | x | x | x |
YDDXSUB | Exit Sub Case | x | x | x | x | x | x | x | x | x | x | x | x |
YDDXDPAR | A(DARPPAR) | x | x | x | x | x | x | x | x | x | x | x | x |
YDDXLOGL | Länge LOGON Mess. | x | x | x | x | ||||||||
YDDXLOGM | A(LOGON Message) | x | x | x | x | ||||||||
YDDDVEC - DCAM-interner Arbeitsbereich
Feldname | Feldinhalt | Exit Case | |||||||||||
APP | CON | ||||||||||||
OPN | CLS | SHU | TRM | FCL | ACQ | ACC | CPL | REQ | CLS | FCL | BAD | ||
YDDVXTID | A(TID) | x | x | x | x | x | x | x | x | x | x | x | x |
YDDVADAC | A(DACB) | x | x | x | x | x | x | x | x | x | x | x | x |
YDDVADCC | A(DCCB) | x | x | x | x | x | |||||||
YDDVADRP | A(DRPB) | x | x | x | |||||||||
YDDVARPB | A(RPB) | x | x | x | x | ||||||||
YDDVAPCN | A(PCN) *) | x | x | ||||||||||
YDDVAPTN | A(PTN) *) | x | x | ||||||||||
*) | Bei Anstoß des Exits durch das Ereignis CONREQ existiert noch kein Verbindungssteuerblock (DCCB). Der Benutzer kann sich mithilfe von YDDVAPTN über die Partneradresse informieren, jedoch nicht modifizieren.
|
Rückkehrinformation der Exit-Routine
Bei den Aufrufereignissen APPCLS, APPSHU, APPTRM, APPFCL, CONCPL, CONCLS, CONFCL und CONBAD muss die Exit-Routine das rechte Byte im Feld YDDXRETC auf null setzen (RC = X'00'). An diesen Aufrufereignissen kann nur Information an die Exit-Routine übergeben werden, die DCAM-Verarbeitung kann nicht durch die Exit-Routine beeinflusst werden.
Bei den Aufrufereignissen APPOPN, CONACQ, CONACC und CONREQ kann die Exit-Routine über den Returncode im Feld YDDXRETC des Parameterbereichs die DCAM-Verarbeitung beeinflussen. Welche Returncodes zu setzen sind, zeigt die folgende Tabelle.
Returncodes (1)
Bedingung | Exit Case | |||||
APPOPN | CONACQ | CONACC | CONREQ | |||
YDDXRETC | RC = 00 | x | x | x | x | |
RC = 04 | x | x | x | x | ||
RC = 08 | x | x | x | - | ||
FDBK | RC = 04 | + | + | + | + | |
YDDEXPL | YDDXPW | RC = 08 | * | * | - | - |
YDDXLOGL | RC = 08 | - | * | * | - | |
YDDXLOGM | YDDXLOGL > 0 | - | * | * | - | |
Erläuterung:
x: der Wert/das Feld kann angegeben werden
-: der Wert/das Feld kann nicht angegeben werden
+: das Feld muss angegeben werden, wenn die Bedingung zutrifft
*: das Feld kann bei RC = 08 verändert an DCAM zurückgegeben werden
Die in der vorangehenden Tabelle mit '*' gekennzeichneten Fälle sind in der folgenden Tabelle näher erläutert.
Returncodes (2)
Exit-Case | Feld in YDDEXPL | Modifikation |
APPOPN | YDDXPW | das RDF-Kennwort (Parameter USEPW im ACB) wird beim BCAM-Aufruf durch das übergebene Kennwort ersetzt; |
CONACC | YDDXLOGL | YDDXLOGL = 0: die Verbindungsnachricht wird nicht verändert |
CONACC | YDDXLOGM | die Verbindungsnachricht (LOGON Message) des Benutzers (Inhalt von AREA) wird vor dem BCAM-Aufruf durch die übergebenen Daten ersetzt |
CONACQ | YDDXPW | das LOGON-Kennwort (Parameter LOGPW im CCB) wird vor dem BCAM-Aufruf durch das übergebene Kennwort ersetzt |