ACTIVATE-USER-EXIT Benutzerausgang aktivieren

Diese Anweisung stellt die Benutzerausgänge für die SHOW-ELEMENT bzw. die COMPARE-ELEMENT Funktion bereit.

Mit ACTIVATE-USER-EXIT verzweigt LMS vor der Bearbeitung eines Elementsatzes in eine Benutzerroutine.

Folgende Aktionen sind vor der Bearbeitung des Elementsatzes durch LMS möglich:

• Verändern des aktuellen Elementsatzes

• Einfügen von Sätzen durch die Benutzerroutine

• Ausschließen des aktuellen Elementsatzes von der Bearbeitung

Der Benutzerroutine werden Beginn und Ende des Elementes mitgeteilt, somit können auch vor dem ersten und nach dem letzten Elementsatz vom Benutzer Sätze eingefügt werden.

Für COMPARE-ELEMENT werden zwei Benutzerausgänge angeboten: einer für das Primärelement und einer für das Sekundärelement. Die Benutzerausgänge für SHOW-ELEMENT und COMPARE-ELEMENT können gleichzeitig definiert werden.

Werden mehrere ACTIVATE-USER-EXIT mit dem gleichen Benutzerausgang angegeben, gilt immer der zuletzt angegebene.

Die aktivierten Benutzerausgänge können mit der Anweisung DEACTIVATE-USER-EXIT wieder deaktiviert werden.

Die ACTIVATE-USER-EXIT-Anweisung erfordert die Angabe der Funktion, für die der Benutzerausgang aktiviert werden soll, und des Einsprungpunktes des Benutzerprogramms. Alle anderen Parameter sind voreingestellt, d.h. das Benutzerprogramm wird standardmäßig aus der TASKLIB-Bibliothek nachgebunden.

ACTIVATE-USER-EXIT

FUNCTION = *SHOW-ELEMENT / *COMPARE-ELEMENT(...)
	*COMPARE-ELEMENT(...)
		|	ELEMENT = *PRIMARY / *SECONDARY
,ENTRY = <name 1..8>
,LIBRARY = *TASKLIB / *OMF / <filename 1..54>
,INTERFACE-VERSION = *V1 / *V2

FUNCTION = *SHOW-ELEMENT / *COMPARE-ELEMENT(...)

Bestimmt diejenige LMS-Anweisung, für die der Benutzerausgang aktiviert werden soll.

FUNCTION = *SHOW-ELEMENT
Benutzerausgang für die SHOW-ELEMENT-Funktion. Sie gilt für alle textartigen Elementtypen und R, F, H und U bzw. davon abgeleitete Elementtypen.

FUNCTION = *COMPARE-ELEMENT(...)
Benutzerausgang für die COMPARE-ELEMENT-Funktion. Sie gilt für alle textartigen Elementtypen und R, F, H und U bzw. davon abgeleitete Elementtypen.

ELEMENT = *PRIMARY / *SECONDARY
Wird der Benutzerausgang für die Anweisung COMPARE-ELEMENT aktiviert, muss noch festgelegt werden, ob es sich um ein Primär- oder um ein Sekundärelement handelt.

ENTRY = <name 1..8>
Maximal 8 Zeichen langer Name des Einsprungpunktes der Benutzerroutine. Der Name darf nicht mit der Zeichenfolge ’LMS’ beginnen.

LIBRARY = *TASKLIB / *OMF / <filename 1..54>
Quelle, in der sich der Benutzermodul befindet.

LIBRARY = *TASKLIB
Der gewünschte Modul wird aus der TASKLIB nachgebunden (siehe Abschnitt „Nachladen des Benutzerprogramms“, "ACTIVATE-USER-EXIT Benutzerausgang aktivieren").

LIBRARY = *OMF
Der gewünschte Modul wird aus *OMF nachgebunden.

LIBRARY = <filename 1..54>
Der gewünschte Modul wird aus der angegebenen Bibliothek nachgebunden.

INTERFACE-VERSION = *V1 / *V2
Es existieren zwei Schnittstellen-Versionen. Aus Kompatibilitätsgründen werden standardmäßig die Werte BOE, REC und EOE angeboten. Durch die Angabe von V2 wird die Schnittstelle um die Werte C’BOS’ (Beginn of Statement) und C’EOS’ (End of Statement) erweitert. Dadurch wird dem Benutzerprogramm Anweisungsbeginn und -ende mitgeteilt.

Anweisungs-Returncode

(SC2)        SC1	Maincode	Bedeutung
0 1 32 64 130	CMD0001 CMD0230 LMS1002 LMS1004 LMS0041	Ohne Fehler Syntaxfehler Interner Fehler Sonstige Fehler Systemadressraum erschöpft

Notwendige Zugriffsrechte

Das Benutzerprogramm wird dynamisch zugebunden. Die Zugriffsrechte hängen damit vom Verhalten des BIND-Makros ab.

Nachladen des Benutzerprogramms

Das Benutzerprogramm wird immer in den benutzereigenen Klasse-6-Speicher geladen. Fehlt bei LIBRARY die Angabe einer Bibliothek, wird das Benutzerprogramm zuerst in einer eventuell vorhandenen privaten Tasklib gesucht (mit /SET-TASKLIB LIBRARY=bibliothek zugewiesen) und dann in der Tasklib des Systems $TASKLIB. Wurde LIBRARY = *OMF oder eine Datei angegeben, aber das Benutzerprogramm dort nicht gefunden, so wird das Benutzerprogramm in der mit LINK=BLSLIB bzw. in den mit LINK=BLSLIBnn
(00 ≤ nn ≤ 99) zugewiesenen Bibliotheken mit aufsteigender Nummer „nn“ gesucht.

Schnittstelle des Benutzerausgangs

• Registerkonventionen

  Beim Aufruf des Benutzerprogramms werden von LMS folgende Registerkonventionen berücksichtigt:

  Register 1:	Adresse einer Parameterleiste
  Register 13:	Adresse des Sicherstellungsbereiches (18 Worte)
  Register 14:	Rücksprungadresse
  Register 15:	Adresse des Einsprungpunktes

• Aufbau der Parameterleiste

  Die Parameterleiste besteht aus 5 Worten:

  DC A(Auftragsbeschreibung)
  DC A(Antwortbeschreibung)
  DC A(zu übergebender Satz)
  DC A(Bibliotheksname)
  DC A(Elementbezeichnung) 
  

  Die ersten beiden Adressen werden von LMS versorgt, d.h. insbesondere, dass der Benutzer die Antwortbeschreibung nur an der von LMS vorgegebenen Adresse abliefern darf. Die Satzadresse kann sowohl von LMS als auch vom Benutzer versorgt werden.

  1. Wort: Auftragsbeschreibung

  Die Auftragsbeschreibung an das Benutzerunterprogramm besteht aus 3 Byte und kann folgenden Inhalt haben:

  C’BOE’ C’REC’ C’EOE’

  Beginn des Elementes Satz steht zur Verarbeitung an Ende des Elementes

  Wurde die erweiterte Schnittstelle gewählt, dann kann die Auftragsbeschreibung folgenden Inhalt haben:

  C’BOS’ C’BOE’ C’REC’ C’EOE’ C’EOS’

  Beginn der Anweisung Beginn des Elementes Satz steht zur Verarbeitung an Ende des Elementes Ende der Anweisung

  2. Wort: Antwortbeschreibung

  Die Antwortbeschreibung vom Benutzerunterprogramm besteht aus 3 Byte und kann folgenden Inhalt haben:

  C’CON’	LMS verarbeitet den Satz, dessen Adresse nach Rückkehr vom Benutzerprogramm in der Parameterleiste steht und bietet danach dem Benutzerprogramm den nächsten Elementsatz oder EOE an.
  C’DEL’	LMS übergeht den zuletzt angebotenen Elementsatz und springt mit dem nächsten Elementsatz oder EOE erneut zum Benutzerunterprogramm.
  C’INS’	LMS verarbeitet zunächst den vom Benutzer zur Verfügung gestellten Satz und kehrt danach mit dem vorher angebotenen Elementsatz oder EOE an das Benutzerunterprogramm zurück; dies wird solange wiederholt, bis der Benutzer mit DEL oder CON antwortet; d.h. wenn LMS den Satz i anbietet, werden die mit INS zurückgesandten Sätze vor dem Satz i bearbeitet.

  Auf die Aufträge kann wie folgt geantwortet werden:

  Auftrag	Antwort
  BOS	nicht relevant
  BOE	nicht relevant
  REC	CON, DEL, INS
  EOE	CON, INS
  EOS	nicht relevant

  Bei falscher Antwort wird die LMS-Funktion mit einer Fehlermeldung abgebrochen.

  Zur Verdeutlichung der Kommunikation zwischen LMS und dem Benutzerunterprogramm siehe Diagramm.

  3. Wort: Satz

  Dieses Wort enthält die Adresse des Satzes, der von LMS an das Benutzerunterprogramm übergeben wird. Kehrt das Benutzerunterprogramm mit der Antwort CON oder DEL zurück, kann die gleiche Satzadresse verwendet werden. Möchte der Benutzer Sätze einfügen, muss er einen eigenen Satzpuffer verwenden.
  Die zwischen LMS und dem Benutzerunterprogramm ausgetauschten Sätze beginnen mit einem 4 Byte langen Satzlängenfeld.
  Zum Auflisten von Typ P Elementen mit SHOW-ELEMENT muss das 5. Byte ein gültiges Vorschubsteuerzeichen sein.

  4. Wort: Bibliotheksname

  Dieses Wort enthält die Adresse des Bibliotheksnamens der von LMS aktuell bearbeiteten Bibliothek. Der Bibliotheksname beginnt mit einem 2 Byte langen Satzlängenfeld.

  5. Wort: Elementbezeichnung

  Dieses Wort enthält die Adresse der Elementbezeichnung des von LMS aktuell bearbeiteten Elementes. Die Elementbezeichnung hat die Form: 2 Byte langes Satzlängenfeld, gefolgt von (Typ)Elementname/Version[(Variantennummer)]/Datum

  

Bild 10: Kommunikation zwischen LMS und Benutzerprogramm

Ein Ablaufbeispiel zum Benutzerausgang siehe "Verzweigen in ein Benutzerprogramm beim Auflisten eines Elementes".

Beispiele

• Minimal-Angabe für die Anweisung ACTIVATE-USER-EXIT.
  Das Benutzerprogramm module1 wird für die SHOW-ELEMENT-Funktion als Benutzerausgang bereitgestellt.

  //activate-user-exit function=*show-element, entry=module1

• Das gewünschte Benutzerprogramm befindet sich in der *OMF-Bibliothek.

  //activate-user-exit function=*show-element, entry=module1,library=*omf