Benutzerroutinen

#### Search Results

Search

# Benutzerroutinen

Eine Benutzerroutine trennt eine SYSOUT-Datei in mehrere Reports. Ein neuer Report beginnt jedes Mal, wenn die Routine auf einer SYSOUT-Seite an einer bestimmten Zeilen/Spaltenposition einen neuen Wert findet.

Dieser Abschnitt beschreibt die Schnittstelle der Benutzerroutinen sowie einige Beispiele mitgelieferter Benutzerroutinen. Benutzerroutinen bestimmen den Inhalt eines Reports. Die Inhalte eines Reports sind ein zusammenhängender Teil oder Teile in einer SYSOUT-Datei.

Wenn für einen Report Benutzerroutinen definiert sind (siehe Trennungsattribute (Separation) im Abschnitt Attribute eines Reports definieren), werden sie für jeden Satz in der zugrunde liegenden SYSOUT-Datei aufgerufen. Eine Routine kann den Monitor aber auch anweisen, von einer anderen Position in der SYSOUT-Datei auszugehen.

Dieser Abschnitt behandelt folgende Themen:

- Benutzerroutinen erstellen

- Beispiele

- Aktionen

- Parameter

## Benutzerroutinen erstellen

Benutzerroutinen werden normalerweise in Natural geschrieben. Es können aber auch andere Sprachen benutzt werden, sofern die Schnittstelle zum Monitor korrekt definiert wird.

Die Routine kommuniziert mit dem Monitor mittels eines Parameterbereichs. Dieser Datenbereich enthält verschiedene Parameter. Einige können von der Routine geändert und an den Monitor zurückgegeben werden, andere können nur gelesen, aber nicht geändert werden.

Die Liste der Parameter ist fest vorgegeben. Format, Länge, Anzahl und Position der Parameter innerhalb der Liste müssen eingehalten werden.

Ein Parameterbereich (PDA/Parameter Data Area) namens `P-UEXIT` wird mitgeliefert und sollte von Benutzerroutinen verwendet werden.

## Beispiele

Die Bibliothek `SYSNOMS` enthält Beispiele zur Anwendung der Parameter, die im folgenden unter Aktionen beschrieben sind.

Falls nicht bereits geschehen, kopieren Sie die Beispiele in die Bibliothek `SYSNOMU` (siehe Anpassung an eine vorhandene Umgebung in der Installation-Dokumentation).

Sie können diese Beispiele ausprobieren, indem Sie das Programm `UEXEMPL` in einem Stapeljob ausführen. Katalogisieren Sie das Programm zuerst, damit es auf die aktuelle `EMPLOYEES`-Datei zeigt. Das Kommando `TRACE` kann dann zum Testen benutzt werden.

Folgende Programme stehen zur Verfügung:

Beispiel-Report | Exit | Beschreibung | Aktionen
--- | --- | --- | ---
`UEX-ADDFP-OPEN` | `UEXAOP` | Trennt die SYSOUT-Datei abhängig vom Gruppenwechsel der Hauptabteilung in mehrere Reports. | `FORW`, `ADDFP`, `OPEN`.
`UEX-CREATE` | `UEXCRE` | Trennt die SYSOUT-Datei abhängig vom Gruppenwechsel der Abteilung in mehrere Reports. | `CREATE`.
--- | `UEXDEF` | Trennt die SYSOUT-Datei abhängig von den Spool-Attributen in mehrere Reports. | `CREATE`
`UEX-FORW-BACKW` | `UEXFBT` | Vorwärts und rückwärts positionieren. | `FORW`, `BACKW`, `GOTOP`, `NEXTP`.
`UEX-GO` | `UEXGGN` | Vorwärts und rückwärts positionieren. | `GOTO`, `GOTOP`, `NEXTP`.
`UEX-UNSL-ADDP` | `UEXAPI` | Erste Zeile einer Seite ersetzen. | `INSL`, `ADDP`.

## Aktionen

- Verschiedene Aktionen

- Aktionen zum Festlegen von Positionen

- Text in einen Report einfügen

- Mit einem Aufruf der Routine mehr als eine Zeile verarbeiten

Folgende Aktionen können von einer Benutzerroutine aufgerufen werden, um die Verarbeitung zu beeinflussen. Jede Aktion basiert auf verschiedenen, weiter unten beschriebenen Parametern.

### Verschiedene Aktionen

Aktion | Beschreibung
--- | ---
`CACHEON` | Caching von Quell-Datensätzen einschalten. Entire Output Management stellt 126 Datensätze in den Cache (Zwischenspeicher), wodurch das Leistungsverhalten erheblich verbessert wird, wenn der Exit auf einer Seite neu positioniert wird. Diese Aktion ist die Voreinstellung.
`CACHEOFF` | Caching von Quell-Datensätzen ausschalten.
`BUNDLE` | Report zu einem aktiven Bündel hinzufügen.

### Aktionen zum Festlegen von Positionen

Aktion | Beschreibung
--- | ---
`GOTOP` | Den Monitor an den Anfang der aktuellen Seite positionieren. Beim nächsten Aufruf wird der am Anfang der aktuellen Seite stehende Satz an die Routine übergeben. Der Anfang der Seite wird entweder durch Kanal 1 ANSI oder durch Maschinencode gefunden.
`GOTO` | Positionieren auf der Satznummer, die im Parameter `P-RECNO` zurückgegeben wird.
`NEXTP` | An den Anfang der nächsten Seite gehen.
`FORW`, `BACKW` | Anzahl der Zeilen in `P-RECNO`.

### Text in einen Report einfügen

Aktion | Beschreibung
--- | ---
`INSL` | Bis zu zehn Zeilen an der aktuellen Position einfügen. Die Anzahl der einzufügenden Zeilen wird in Parameter `P-RECNO` zurückgegeben. Die einzufügenden Textzeilen stehen im Parameter `P-INSERT-LINES`.

### Mit einem Aufruf der Routine mehr als eine Zeile verarbeiten

Aktion | Beschreibung
--- | ---
`ADDR` | Zeilenbereich hinzufügen, wobei die Satznummern des einzufügenden Bereiches in den Parametern `P-FROMLINE` und `P-TOLINE` zurückgegeben werden. Der nächste Aufruf der Routine beginnt mit der Zeile nach dem letzten Satz des angegebenen Bereiches (`P-TOLINE` + 1).
`ADDP` | Dem aktuellen Report alle Sätze von der aktuellen Zeile bis zum Ende der aktuellen Seite hinzufügen. Der nächste Aufruf der Routine beginnt am Anfang der nächsten Seite.
`ADDFP` | Dem aktuellen Report die gesamte aktuelle Seite hinzufügen. Der nächste Aufruf der Routine beginnt am Anfang der nächsten Seite.
`CREATE` | Einen Report erstellen aus den Sätzen, deren Nummern in den Parametern `P-FROMLINE` und `P-TOLINE` angegeben sind. Die Nummer des zu erstellenden Reports muss im Parameter `P-REPNAME` zurückgegeben werden. Wenn der Report in der Master-Datenbank nicht definiert ist, wird er dort dynamisch erstellt unter Verwendung der Parameter, die von der Routine zurückgegeben werden. Wenn diese Aktion angegeben wird und es einen bereits geöffneten Report gibt, wird dieser Report zuerst geschlossen. Der nächste Aufruf der Routine beginnt mit der Zeile nach dem letzten Satz im angegebenen Bereich (`P-TOLINE` + 1).
`OPEN` | Aktuellen Report schließen und neuen Report öffnen. Der Name des neuen Reports muss im Parameter `P-REPNAME` zurückgegeben werden.
`CLOSE` | Aktuellen Report schließen. Parameter für die Report-Verarbeitung können überschrieben werden, falls sie in den Exit-Parametern zur Verfügung gestellt werden.

## Parameter

In diesem Abschnitt sind die Parameter für Benutzerroutinen beschrieben:

- Allgemeine Parameter

- Quellen-Parameter

- Bündel-Parameter

- Report-Parameter

### Allgemeine Parameter

Parameter | Beschreibung
--- | ---
`P-RC` | Return-Code, der angibt, ob der aktuelle Satz in den Report aufgenommen werden soll oder nicht. Wird vom Exit an den Monitor zurückgegeben. Mögliche Werte: `0` = aktuellen Satz in den Report aufnehmen; `1` = aktuellen Satz ignorieren; 3 = Ende der Verarbeitung, Report schließen.
`P-ACTION` | Aktionscode, der den Monitor anweist, eine bestimmte Aktion auszuführen.
`P-MASTER` | Name der Master- oder Standard-Reportdefinition, die gerade verarbeitet wird.
`P-UPARM1` | Ein Bereich (Vektor) von fünf Parametern, die vom Monitor an die Routine übergeben geben. Die Werte sind in der entsprechenden Master- oder Standard-Reportdefinition enthalten. Werten Sie diese Parameter beim ersten Aufruf der Routine aus oder sichern Sie sie.
`P-RECNO` | Aktuelle Satznummer innerhalb der gerade verarbeiteten Quelle.
`P-RECORD` | Inhalt des aktuellen Satzes.
`P-INSERT-LINES` | Ein Bereich (Vektor) von zehn Zeilen, der mit der Aktion `INSL` eingefügt werden kann.
`P-FROMLINE` | Satznummer des ersten Satzes eines Zeilenbereiches. Wird benutzt von Aktionen, die Zeilen zum aktuellen aktiven Report hinzufügen.
`P-TOLINE` | Satznummer des letzten Satzes eines Zeilenbereiches. Wird benutzt von Aktionen, die Zeilen zum aktuellen aktiven Report hinzufügen.
`P-WORK` | Arbeitsbereich für Benutzerroutinen, um Daten für spätere Aufrufe zu sichern.

### Quellen-Parameter

- Parameter für alle Quellen
- Parameter für Quellen-Typ POWER
- Parameter für Quellen-Typ Sequentielle Datei z/VSE

#### Parameter für alle Quellen

Parameter | Beschreibung
--- | ---
`P-SOURCE-TYPE` | Gibt den Typ der zu verarbeitenden Quelle an:
1 | JES2
2 | JES3
3 | POWER
4 | Entire Output Management-Datenbank (Container-Datei)
5 | Sequentielle Datei (z/OS)
6 | Sequentielle Datei (z/VSE)
7 | BS2000
11 | Natural Advanced Facilities
14 | CA Spool
`P-SOURCE-CC-TYPE` | Gibt den Typ der Vorschubsteuerzeichen an:
1 | ASA
2 | Maschinencode
3 | reserviert für BS2000
4 | keine Vorschubsteuerzeichen
`P-SOURCE-NUMBER-OF-LINES` | Gesamtanzahl der Zeilen in der Quelle.
`P-MAXREC` | Siehe `P-SOURCE-NUMBER-OF-LINES` oben. Dieser Parameter ist aus Kompatibilitätsgründen noch verfügbar, wird aber in der nächsten Version gelöscht sein.
`P-SOURCE-RECORD-LENGTH` | Aktuelle Länge des Satzes in Bytes einschließlich des Vorschubsteuerzeichens (falls vorhanden). Darf nicht verändert werden.
`P-RECLEN` | Siehe `P-SOURCE-RECORD-LENGTH` oben. Dieser Parameter ist aus Kompatibilitätsgründen noch verfügbar, wird aber in der nächsten Version gelöscht sein.
`P-SOURCE-ATTRIBUTES` | Quellenspezifische Attribute, welche abhängig von `P-SOURCE-TYPE` redefiniert werden, sind in dem nächsten Abschnitt beschrieben.

#### Parameter für Quellen-Typ POWER

Parameter | Beschreibung
--- | ---
`P-POWER-NODE` | Entire System Server Knoten, von dem die Quelle gelesen wird.
`P-POWER-JOB-NAME` | Jobname der SYSOUT-Daten, die gerade verarbeitet werden.
`P-POWER-JOB-NUMBER` | POWER-Jobnummer der SYSOUT-Daten, die gerade verarbeitet werden.
`P-POWER-TYPE` | Der Typ für die POWER List Queue ist immer LS.
`P-POWER-SEGMENTS` | Anzahl der Segmente.
`P-POWER-SEG-LASTLINE` | Ein Bereich (Vektor) von bis zu 40 Ausprägungen. Gibt die letzte logische Zeile für jedes Segment an.

#### Parameter für Quellen-Typ Sequentielle Datei z/VSE

Parameter | Beschreibung
--- | ---
`P-FVSE-NODE` | Entire System Server Knoten, von dem die aktuelle Quelle gelesen wird.
`P-FVSE-VOLSER` | Nummer des Datenträgers (Volume Serial Number), auf dem die Datei steht.
`P-FVSE-DSNAME` | Name der Datei.
`P-FVSE-RECFM` | Satzformat der Datei.
`P-FVSE-LRECL` | Satzlänge der Datei.
`P-FVSE-BLKSIZE` | Blocklänge der Datei.

### Bündel-Parameter

Diese Parameter werden benutzt, um Reports dynamisch in Bündeln zusammenzufassen.

Parameter | Beschreibung
--- | ---
`P-BUNDLE` | Ein Bereich (Vektor) von bis zu fünf Bündeln, in die der Report aufgenommen wird.
`P-BUNDLE-COORDINATOR` | Benutzerkennung des Bündel-Koordinators.
`P-FLUSH-TIME` | Zeit, zu der das Bündel geschlossen und gedruckt werden soll.
`P-BUNDLE-FLUSH-LINES` | Anzahl Zeilen, bei denen das Bündel geschlossen und gedruckt werden soll.
`P-BUNDLE-SEPSTART` | Trennblatt, das am Anfang des Bündels gedruckt wird.
`P-BUNDLE-SEPEND` | Trennblatt, das am Ende des Bündels gedruckt wird.
`P-BUNDLE-SEPNO` | Anzahl der Trennblattexemplare.
`P-BUNDLE-PRINTER` | Drucker, auf dem das Bündel gedruckt werden soll.
`P-BUNDLE-JOBCARDS` | Bis zu drei Jobkarten, die beim Drucken im Batchmodus benutzt werden.
`P-BUNDLE-GROUP` | Bis zu fünf Bündelgruppen.
`P-BUNDLE-SEQUENCE-NR` | Bis zu fünf Sequenz-Nummern.
`P-BUNDLE-REPORT-SEPARATORS` | Report-Trennblätter des Bündels.
`P-BUNDLE-PRINTERS` | Bis zu zwanzig Bündel-Drucker.
`P-BUNDLE-PRINTERS-COPY` | Bis zu zwanzig Bündel-Druckerkopien.
`P-BUNDLE-HOLD` | Bündel im Hold-Status
`P-BUNDLE-GRANT` | Bis zu 6 zugelassene Benutzer (`P-BUNDLE-GRANTED-USER`) für die von diesem Exit erstellten Bündel. Jede Angabe besteht aus Benutzerkennung und deren Zulassungsoptionen (`P-BUNDLE-GRANT-OWNER`, `-MODIFY`, `-PURGE`, `-DISPLAY`, `-ARCHIVE`, `-REVIVE`). Zulassungs-Optionen sollten auf `Y` oder `N` gesetzt werden.
`P-BUNDLE-DESCRIPTION` | Beschreibung des Bündels.
`P-CONTROL-EXIT-LIBRARY` | Natural-Bibliothek, welche den Druck-Kontroll-Exit des Bündels enthält.
`P-CONTROL-EXIT-MEMBER` | Name des Druck-Kontroll-Exits des Bündels.
`P-BUNDLE-FLUSH-REPORT` | Bis zu 4 Report-Namen, was zum Löschen des Bündels führt.
`P-BUNDLE-FLUSH-START` | Geplante Lösch-Startzeit im Format HHII (Stunden und Minuten).
`P-BUNDLE-FLUSH-END` | Geplante Lösch-Endzeit im Format HHII (Stunden und Minuten). Sie muss größer als `P-BUNDLEFLUSH- START` sein.
`P-BUNDLE-FLUSH-INT` | Geplantes Lösch-Zeitintervall im Format HHII (Stunden und Minuten).
| Alle 3 der obengenannten Parameter sind anzugeben, oder der Lösch-Plan wird ignoriert.
`P-BUNDLE-FLUSH-DAYS` | Tage des Monats, wann das Bündel gelöscht werden sollte. Muss im Bereich 1-31, ALL oder LD sein.
`P-BUNDLE-FLUSH-WEEK-DAYS` | Tage der Woche, wann das Bündel gelöscht werden sollte. Es sind die ersten zwei Buchstaben des Tages anzugeben. Englisch: `SA`, `SU`, `MO`, `TU`, `WE`, `TH`, `FR`. Deutsch: `SA`, `SO`, `MO`, `DI`, `MI`, `DO`, `FR`.
`P-BUNDLE-FLUSH-CALENDAR` | Für die Unterscheidung zwischen Feier- und Arbeitstagen zu benutzender Kalender - muss spezifiziert werden, wenn `P-BUNDLE-FLUSH-BEFORE-AFTER` angegeben wird.
`P-BUNDLE-FLUSH-BEFORE-AFTER` | `A` oder `B` zum Löschen des Bündels nach oder vor einem in dem angegebenen Kalender als Feiertag definierten Tag.

Wenn einer der Bündel-Lösch-Parameter ungültig ist, werden sie alle ignoriert, und es wird eine Fehlermeldung in die Monitor-Ausgabeliste geschrieben.

### Report-Parameter

Parameter | Beschreibung
--- | ---
`P-REPNAME` | Wird für die Aktionen `OPEN` und `CREATE` benutzt, um den zu verarbeitenden Report anzugeben.
`P-REPORT-DESCRIPTION` | Langbeschreibung des Reports.
`P-OWNER` | Master-Eigentümer des Reports.
`P-KEYWORDS` | Ein Bereich (Vektor) von bis zu sechs Schlüsselwörtern, die benutzt werden, wenn der Report erstellt oder beim Schließen überschrieben wird.
`P-STORE-NRM` | Wird nur beim Öffnen oder Erstellen neuer Reports benutzt. `Y` bedeutet, dass der Report in der Entire Output Management Datenbank gespeichert wird.
`P-DISTRIBUTION` | Ein Bereich (Vektor) von bis zu zehn Empfängern für die Verteilung. Wird beim Erstellen und Öffnen benutzt.
`P-PRINTERS` | Ein Bereich (Vektor) von bis zu zwanzig logischen Druckern, auf denen der Report ausgegeben werden soll. Wird bei den Aktionen `CREATE`, `OPEN` und `CLOSE` zum Überschreiben benutzt.
`P-COPIES` | Anzahl der Exemplare des Reports, die auf jedem in `P-PRINTERS` angegebenen Drucker ausgegeben werden sollen.
`P-HOLD` | Status für Druckaufträge. Bei den Aktionen `CREATE`, `OPEN` und `CLOSE` zum Überschreiben benutzt. Mögliche Werte: `H` = Druckauftrag halten. `R` = Druckauftrag freigeben. `C` = Bestätigung aller Benutzer für die Freigabe erforderlich.
`P-REPORT-SEPSTART` | Trennblatt, das am Anfang des Reports gedruckt wird.
`P-REPORT-SEPEND` | Trennblatt, das am Ende des Reports gedruckt wird.
`P-REPORT-SEPNO` | Anzahl der Trennblattexemplare.
`P-REPORT-JOBCARDS` | Bis zu drei Jobkarten, die beim Drucken im Batch-Modus benutzt werden.
`P-ARCHIVE` | `Y` = Der Report wird beim Erstellen zum Archivieren markiert.
`P-RETENTION-NUM` | Anzahl der Einheiten der Aufbewahrungszeit (siehe unten), die der Report-Inhalt online verfügbar sein soll.
`P-RETENTION-UNIT` | Einheit für die Aufbewahrungszeit: `W` = Arbeitstage. `A` = Absolute Tage. `V` = Wochen. `M` = Monate.
`P-RETENTION-CALENDAR` | Name des Kalenders, in dem die Arbeitstage definiert sind.
`P-RETENTION-ACTION` | Wird bei den Aktionen `CREATE`, `OPEN` und `CLOSE` zum Überschreiben benutzt. `P` = Report nach Ablauf der Aufbewahrungszeit löschen. `A` = Report nach Ablauf der Aufbewahrungszeit archivieren.

### On this page

- Benutzerroutinen erstellen
- Beispiele
- Aktionen
- Parameter