Event-Exit INPUT

Mit diesem Event-Exit kann die Wirkung einer Terminal-Eingabe bestimmt werden.

openUTM ruft den Event-Exit INPUT - mit einigen Ausnahmen - bei jeder Eingabe von einem Terminal auf. Diese Ausnahmen sind:

• Eingaben, wenn noch kein Benutzer angemeldet ist

• Eingaben im Event-Service SIGNON

• Eingaben mittels einer mit SFUNC generierten Funktionstaste

• Eingaben, nachdem ein Programm den Aufruf SIGN OB/OF gegeben hat

openUTM übergibt dem Programm für einen INPUT-Exit die Adresse eines Parameterbereichs, welcher aus einem Eingabebereich und einem Ausgabebereich besteht.

Für die Deklaration des Parameterbereichs stehen Ihnen Sprach-spezifische Datenstrukturen zur Verfügung, für COBOL das COPY-Element KCINPC, für C/C++ die Include-Datei kcinp.h. Die einzelnen Felder des Parameterbereichs sowie die Bedeutung der einzelnen Felder sind auf den folgenden Seiten ab Tablelle „Parameterbereich KDCINPC/kdcinp.h" beschrieben.

Auf BS2000-Systemen übergibt openUTM dem Input-Exit zusätzlich einen zweiten Parameter, der weitere Eingabefelder enthält. Auch für die Strukturierung des 2. Parameters steht eine Sprach-spezifische Datenstruktur zur Verfügung, für COBOL das COPY-Element KCCFC und für C/C++ die Include-Datei kccf.h. Der 2. Parameterbereich ist auf den Seiten ab Abschnitt „Zweiter Parameterbereich KCCFC/kccf.h (für BS2000-Systeme)" beschrieben.

Das Programm analysiert die in den Eingabefeldern eingetragenen Werte und versorgt daraufhin den Ausgabebereich. Aufgrund der Werte, die im Ausgabebereich eingetragen wurden, entscheidet openUTM, welche der folgende Aktionen ausgeführt werden:

• Fortsetzen eines Vorgangs

• Starten eines neuen Vorgangs

• Kellern eines Vorgangs und Starten eines neuen Vorgangs

• Ausführen eines Benutzer-Kommandos, z.B. KDCOFF

• Senden einer Meldung mit Fehlerinformation an das Terminal

Anwendungsmöglichkeiten

Der Eingabe-Exit bietet für die Terminalschnittstelle zusätzliche Freiheiten bei der Gestaltung der Benutzeroberfläche.

• Position von Transaktionscodes oder KDC-Kommandos in der Nachricht:Transaktionscode oder KDC-Kommando müssen nicht am Anfang der Nachricht stehen.

• Sichtbarkeit der Transaktionscodes am Bildschirm:
  Es ist nicht notwendig, dass ein Transaktionscode auf dem Bildschirm sichtbar wird, wenn man einen Vorgang starten will.
  Beispielsweise kann ein Menü mehrere Tätigkeiten anbieten. Der Terminal-Benutzer, wählt durch Eingabe eines Textes oder einer Nummer eine von ihnen aus. Diese Eingabe muss noch kein Transaktionscode sein, erst der INPUT-Exit setzt sie in einen Transaktionscode (Vorgangs-TAC) um. Damit werden die Transaktionscodes, die ja eine Generierungsinformation sind, von der Dialog-Oberfläche entkoppelt.

• Darstellung von Kommando-Namen:
  Es ist nicht notwendig, die Schreibweise "KDC..." zu verwenden, um die Wirkung eines KDC-Kommandos auszulösen.
  Wenn es zweckmäßig ist, kann man eine andere Darstellung wählen, z.B. "/" an Stelle von "KDC".

Parameterbereich KDCINPC/kdcinp.h
Eingabebereich (wird von openUTM versorgt)
Feldname	Inhalt
KCIFCH	erste 8 Zeichen der Eingabe
KCIMF/kcifn	Formatkennzeichen
KCICVTAC	Transaktionscode des Vorgangs
KCICVST	Vorgangs-Status
KCIFKEY	Wert der F-Taste: 1,...,20 / binär null
KCIKKEY	binär null / auf BS2000-Systemen: Wert der K-Taste: 1,...,20
KCICFINF: "NO"/"MO"/"ON"/"UN" 1	Informationen über die Formatierung
KCILTERM	aktueller LTERM-Partner
KCIUSER	aktuelle Benutzerkennung
Ausgabebereich (vom INPUT-Exit zu versorgen)
Feldname	Inhalt
KCINTAC bzw. KCINCMD	nächster Vorgangs-TAC bzw. nächstes Benutzerkommando
KCICCD	Code für die Wirkung der Eingabe: "ER"/"CC"/"SC"/"ST"/"CD"
KCICUT	TAC abschneiden: "Y"/"N"
KCIERRCD	Fehlerinfo für das Terminal (4 Byte)

¹ "MO" / "ON" / "UN" (nur auf BS2000-Systemen)

In den Eingabebereich trägt openUTM folgende Werte ein:

KCIFCH

In das Feld KCIFCH die ersten 8 Zeichen der Eingabe, höchstens jedoch bis zum ersten Leerzeichen.

KCIMF/kcifn

In das Feld KCIMF/kcifn das Formatkennzeichen:

• Leerzeichen im Zeilenmodus oder

• Formatkennzeichen des Formats, das am Bildschirm steht (nur auf BS2000-Systemen).

Nur auf BS2000-Systemen:
Das Feld KCIMF/kcifn kann auch das Formatkennzeichen #!POPUP enthalten. #!POPUP bedeutet, dass eine Box am Bildschirm steht. Über die FHS-Service-Funktion KDCFHS mit dem USER-CODE INFD können Sie die Namen aller Formate erhalten, die am Bildschirm stehen.

KCICVTAC

In das Feld KCICVTAC den Transaktionscode, mit dem der aktuelle Vorgang gestartet wurde (wenn man sich innerhalb eines Vorgangs befindet).

KCICVST

In das Feld KCICVST den Vorgangs-Status:

• ES (End of dialog Step)
  Ende des Verarbeitungsschritts mit PEND KP oder PGWT KP,

• ET (End of Transaction)
  Ende der Transaktion mit PEND RE,

• RS (Return from Stack)
  Ende des eingeschobenen Vorgangs, die Eingabe ist für den gekellerten Vorgang bestimmt.

• EC (End of Conversation)
  Der letzte Verarbeitungsschritt wurde mit PEND FI beendet, die Eingabe ist für einen neuen Vorgang bestimmt.

KCIFKEY

den Wert der F-Taste (1 - 20, auf BS2000-Systemen: 1 - 24), falls betätigt, sonst binär null.

KCIKKEY

den Wert binär null
oder (auf BS2000-Systemen) den Wert der K-Taste (1 - 14), falls betätigt.

KCICFINF

In das Feld KCICFINF Informationen des Formatierungssystems:

• NO(NO control field)
  Die Eingabe enthält kein Steuerfeld; entweder kam die Eingabe im Zeilenmodus oder (auf BS2000-Systemen) das Format enthält kein Steuerfeld oder in ein Steuerfeld wurde nichts eingegeben.

Nur auf BS2000-Systemen:

• MO (MOre control fields)
  Die Eingabe enthält mehrere Steuerfelder.

• ON (ONe control field)
  Die Eingabe enthält genau ein Steuerfeld.

• UN (UN successful)
  Die Eingabe konnte nicht formatiert werden.
  Daher sind auch keine Angaben über Steuerfelder möglich. Tritt z.B. auf nach einer Eingabe in ein Format, das mit KDCOUT abgeholt worden war.

KCILTERM

In das Feld KCILTERM den Namen LTERM-Partners, über den das Terminal angeschlossen ist.

KCIUSER

In das Feld KCIUSER die aktuelle Benutzerkennung.

In die Felder des Ausgabebereichs tragen Sie ein:

KCINTAC

Wenn ein neuer Vorgang gestartet werden soll:
in das Feld KCINTAC den Transaktionscode des Teilprogramms, das den nächsten Vorgang startet.

KCINCMD

Wenn ein Benutzer-Kommando ausgeführt werden soll:
in das Feld KCINCMD das Benutzerkommando (KDC-Kommando).
Bei einer Fehlermeldung (KCICCD = ER) oder bei Fortsetzen des Vorgangs (KCICCD = CC, Folgetac wird beim PEND eingetragen) müssen Leerzeichen eingetragen werden.

KCICCD

in das Feld KCICCD je nachdem, welche Wirkung die Eingabe haben soll:

• ER (ERror indication)
  für eine Fehlermeldung an das Terminal. In das Feld KCIERRCD kann dann ein Insert für diese Meldung eingetragen werden.

• CC (Continue Conversation)
  für die Fortsetzung des Vorgangs. Dies darf nicht nach Vorgangsende (KCICVST = EC) angegeben werden.

• SC (Start new Conversation)
  wenn ein neuer Vorgang gestartet werden soll; nur nach Vorgangsende erlaubt (KCICVST = EC).

• ST (STack Conversation)
  wenn der aktuelle Vorgang gekellert und ein neuer Vorgang gestartet werden soll; nur erlaubt bei Transaktionsende (KCICVST = ET/RS).

• CD (process CommanD)
  wenn openUTM ein Benutzer-Kommando ausführen soll.

KCICUT

in das Feld KCICUT den Wert Y, falls der TAC bei Vorgangsbeginn abgeschnitten werden soll (nur erlaubt bei KCICCD = SC/ST), sonst N.

KCIERRCD

in das Feld KCIERRCD eine bis zu 4 Byte lange Zeichenfolge, die bei KCICCD=ER mit der Meldung K098 an das Terminal geschickt werden soll. Andernfalls (KCICCD != ER) Leerzeichen.

Zweiter Parameterbereich KCCFC/kccf.h (für BS2000-Systeme)

Mit Hilfe des zweiten Parameters übergibt openUTM die Inhalte der Steuerfelder von Bildschirmformaten an das Teilprogramm. Dieser zweite Parameter wird deshalb auch Steuerfeldbereich genannt. Im Feld KCCFS kann openUTM Eingaben, die in mehreren verschiedenen Steuerfeldern eines Formats (auch verschiedener Teilformate eines Formats) gemacht wurden, übergeben.

Die ersten beiden Felder, KCCFCREM und KCCFCFLD, entsprechen dem Steuerfeldbereich früherer openUTM-Versionen. Sie sind aus Kompatibilitätsgründen noch enthalten. Relevant sind die Felder KCCFNOCF und KCCFS.

Die folgende Tabelle zeigt den Aufbau des Steuerfeldbereichs, in dem openUTM die Eingabeparameter zur Verfügung stellt.

2. Parameterbereich (wird von openUTM versorgt)
Feldname	Inhalt
KCCFCREM (Byte 1 - 8)	erste 8 Zeichen der Eingabe
KCCFCFLD (Byte 9 - 140)	Formatkennzeichen
KCCFNOCF (Byte 141 - 144)	Transaktionscode des Vorgangs
KCCFS (Byte 145 - 7744)	Tabelle (Array) der Steuerfeldinformation, jedes Array-Element enthält die Information zu einem Steuerfeld. Es gibt maximal 50 Elemente. Die Elemente sind wie folgt aufgebaut:
	KCCFFNAM (8 Byte) Name des Formats bzw. Teilformats, das das Steuerfeld enthält
	KCCFREM (8 Byte) Remark wie mit dem IFG definiert
	KCFLOFL (4 Byte) Länge des Steuerfeldes
	KCCFFLD (132 Byte) Inhalt des Steuerfeldes

Im 2. Parameterbereich stellt openUTM folgende Werte zur Verfügung:

KCCFCREM

KCCFCREM enthält den Remark, der bei der Formaterstellung mit dem IFG für das Steuerfeld definiert wurde, dessen Inhalt in KCCFCFLD enthalten ist. Wurde bei der Formaterstellung kein Remark erzeugt oder wurden in das Steuerfeld keine Eingaben gemacht, sind die 8 Byte dieses Feldes mit Leerzeichen belegt.

KCCFCFLD

KCCFCFLD enthält die Eingabe in ein Steuerfeld des Formats, sofern im Format wenigstens ein Steuerfeld definiert ist und in dieses Steuerfeld eine Eingabe gemacht wurde. KCCFCFLD enthält diese Eingabe in der Länge des Steuerfeldes. Der Rest des Feldes KCCFCFLD ist mit Leerzeichen belegt.
Erfolgte keine Eingabe in ein Steuerfeld oder besitzt das Format kein Steuerfeld, so enthalten KCCFCREM und KCCFCFLD Leerzeichen und KCCFNOCF den Wert Null. Besitzt das Format mehrere Steuerfelder, gegebenenfalls in verschiedenen Teilformaten, so beziehen sich Remark und Inhalt des Steuerfeldes auf ein Steuerfeld, in das eine Eingabe erfolgte. Erfolgte eine Eingabe in mehrere Steuerfelder, so erhält KCCFCFLD die Eingabe in das 1. Steuerfeld, in dem Teilformat, das am Bildschirm an der obersten Position steht. KCCFCREM enthält den dazugehörigen Remark.

KCCFNOCF

KCCFNOCF enthält die Anzahl der Steuerfelder des Formats, in die Eingaben gemacht wurden.

KCCFS

KCCFS enthält ein Array, das alle von FHS übergebenen Steuerfelder enthält; auch das Steuerfeld, dessen Daten bereits in den Feldern KCCFCFLD und KCCFCREM stehen. Die Anzahl der gültigen Arrayelemente steht im Feld KCCFNOCF.
Jedes Arrayelement besteht aus einer Struktur, die folgende Felder enthält:

KCCFFNAM

enthält in 8 Byte den (Teil-) Formatnamen des Formats, zu dem das Steuerfeld gehört. Ist der Name kürzer als 8 Zeichen, dann wird der Rest des Feldes mit Leerzeichen belegt.

KCCFREM

enthält den Remark, der bei der Formaterstellung mit dem IFG für dieses Steuerfeld definiert wurde. Wurde bei der Formaterstellung kein Remark erzeugt, sind die 8 Byte dieses Feldes mit Leerzeichen belegt.

KCCFLOFL

Länge des Steuerfeldes.

KCCFFLD

enthält die Eingabe in das Steuerfeld des Formats. KCCFFLD enthält diese Eingabe in der Länge des Steuerfeldes. Der Rest des Feldes KCCFFLD ist mit Leerzeichen belegt.

Eingaben in Steuerfelder (BS2000-Systeme)

Eine Eingabe in ein Steuerfeld kann unterschiedliche Ursachen haben:

• Eingabe des Terminal-Benutzers in das Steuerfeld.

• Das Feld wurde bei der Formatgenerierung mit IFG mit der Eigenschaft "automatische Eingabe" gekennzeichnet.

• Bei ∗Formaten oder +Formaten: Das Feld hat die Feldeigenschaft "ungeschützt" und der FHS-Startparameter ISTD=RUNP (Read unprotected) ist gesetzt.

Fehler beim INPUT-Exit

Bei Fehlern im INPUT-Exit wird ein offener Vorgang nicht beendet; allerdings wird der Benutzer am Terminal mit der Meldung K098 über den Fehler informiert, falls

• der Eintrag in KCICCD (Wirkung der Eingabe) unzulässig ist oder

• der Eintrag in KCICCD nicht zu den Werten der restlichen Ausgabefelder passt.

In beiden Fällen wird zur Diagnose ein UTM-Dump mit REASON=INPERR geschrieben. Auf BS2000-Systemen wird in diesen Fällen zusätzlich ein USERDUMP geschrieben.

Datenbank-Aufrufe sind im INPUT-Exit nicht erlaubt.
Bei DB-Aufrufen wird auf BS2000-Systemen ein USERDUMP mit dem Fehlercode KDCDB10 erzeugt.

Generierungshinweise

Den Event-Exit INPUT muss man bei der Generierung mit der EXIT-Anweisung, Operand USAGE=(INPUT,...) definieren. Man kann auch mehrere INPUT-Exits für unterschiedliche Zwecke definieren. Es stehen folgende Möglichkeiten zur Verfügung:

• Eine Anwendung erhält nur einen universellen INPUT-Exit, der sowohl bei Eingaben im Formatmodus als auch bei Eingaben im Zeilenmodus aufgerufen wird. Generiert wird dieser Universal-Exit mit USAGE=(INPUT,ALL). Weitere INPUT-Exits sind in diesem Fall nicht zulässig.

• Für jede Art des Formatkennzeichens kann ein spezieller INPUT generiert werden. Es gibt mehrere Typen, jeder Typ darf höchstens einmal vorhanden sein:

  • Mit USAGE=(INPUT,LINEMODE) wird ein INPUT-Exit für Eingaben im Zeilenmodus definiert.

  Nur auf BS2000-Systemen:

  • Mit USAGE=(INPUT,FORMMODE) wird ein INPUT-Exit +Formate und *Formate definiert. Ein so generierter INPUT-Exit wird auch bei den #Formaten aufgerufen.

  • Mit USAGE=(INPUT,USERFORM) wird ein INPUT-Exit für benutzereigene Formatierungsroutinen (-Formate) definiert.

Werden in einer Anwendung spezielle INPUT-Exits verwendet, dann darf man keinen universalen Typ mit (USAGE=INPUT,ALL) definieren.