Makrotyp: S-Typ (E-Form/L-Form/D-Form/C-Form) (siehe "Typen von Makroaufrufen")
Der Benutzer kann sich mit dem RDTFT-Makroaufruf Informationen aus der TFT in einen Benutzerbereich ausgeben lassen. Gegebenenfalls erhält er auch Informationen aus dem mit dem TFT-Eintrag verknüpften TST-Eintrag.
Format
Operation | Operanden |
|
|
| |
|
Operandenbeschreibung
ausadr
Symbolische Adresse des Ausgabebereichs, in den die Informationen aus der TFT übertragen werden sollen. Die Angabe dieser Adresse ist obligatorisch bei Angabe von MF=L oder fehlender MF-Angabe.
länge
Länge des Benutzerbereichs
Mindestlänge: 11 Byte; Ausnahme bei NUMONLY=YES: 4 Byte
Voreinstellung: | bei SHORT, PARMOD=24/31: 140 Byte |
FILE = pfadname
legt fest, über welche Datei(en) informiert werden soll, mit:
<c-string 1..80: filename 1..54 with-wild(80)>
Bezeichnet die Datei/Dateigeneration, aus deren TFT-Eintrag Informationen ausgegeben werden sollen.
In „catid“, „userid“ und „dateiname“ können Zeichenfolgen durch Muster ersetzt werden. In diesem Fall darf die Gesamtzeichenfolge für „pfadname“ bis zu 80 Zeichen lang sein. Leere Dateinamen und der Dateiname „*DUMMY“ werden bei Verwendung von Wildcards nicht selektiert.
Ist „pfadname“ eine Dateigeneration, muss die absolute Generationsnummer angegeben werden.
Bei temporären Dateien wird der interne Dateiname ausgegeben.
Pfadname bedeutet [:catid:][$userid.]dateiname
catid
Katalogkennung der Datei; fehlt die Angabe, wird die Default-Catid zugewiesen, die der Userid zugeordnet ist.
userid
Benutzerkennung der Datei; fehlt der Operand, wird die eigene Benutzerkennung angenommen.
dateiname
teil- oder vollqualifizierter Dateiname.
LINK = name
Gibt den Dateikettungsnamen des TFT-Eintrags an, aus dem Informationen in den Ausgabebereich übertragen werden (ggf. zusammen mit Informationen aus dem zugehörigen TST-Eintrag).
In „name“ können Zeichenfolgen durch Muster ersetzt werden. In diesem Fall gilt:
Die Gesamtzeichenfolge darf bis zu 80 Zeichen lang sein.
Die Gesamtzeichenfolge darf außer den Wildcards nur Zeichen aus dem zulässigen Wertebereich der Kommandoschnittstelle enthalten.
Selektiert werden bei der Angabe von Wildcards nur solche TFT-Einträge, deren Dateikettungsname aus Zeichen aus dem zulässigen Wertebereich der Kommandoschnittstelle gebildet wurde.
LINKWC
Nur ab VERSION=2:
legt fest, ob Platzhalterzeichen im Kettungsnamen als Muster oder als gewöhnliche Zeichen interpretiert werden.
= NO
Platzhalterzeichen werden als gewöhnliche Zeichen aufgefasst.
= YES
Platzhalterzeichen werden als Muster aufgefasst.
LONG
Der vollständige TFT-Eintrag und daran anschließend der damit verknüpfte TST-Eintrag einschließlich der Geräteliste werden in den Benutzerbereich übertragen.
MF
Die Formen des MF-Operanden sind detailliert im Anhang ("Typen von Makroaufrufen") beschrieben. In allen Makroaufrufen, die sich durch den MF-Operanden unterscheiden (MF=L/E/D/C), muss der Versionsoperand den gleichen Wert haben.
Ist MF nicht angegeben, erhält man die S-Form; die explizite Angabe MF=S ist jedoch nur für PARMOD=24 möglich.
NUMONLY
Nur ab VERSION=3:
legt fest, ob lediglich die Anzahl der selektierten TFT-Einträge in den Ausgabebereich geschrieben werden soll.
= NO
Die Anzahl der TFT-Einträge wird nicht in den Ausgabebereich übertragen.
= YES
Die selektierten TFT-Einträge werden gezählt und das Ergebnis in die ersten vier Byte des Ausgabebereichs geschrieben. Eine weitere Ausgabe erfolgt nicht. Die Mindestgröße des Ausgabebereichs beträgt 4 Byte.
PARMOD
Gibt den Generierungsmodus für den Makroaufruf an. Werden PARMOD und VERSION zugleich angegeben, wird der PARMOD-Operand ignoriert und eine MNOTE-Meldung erzeugt.
Voreinstellung: | 31, falls VERSION angegeben ist, andernfalls der durch den Makro GPARMOD oder durch den Assembler voreingestellte Wert für den Generierungsmodus |
= 24
Der Makroaufruf wird mit der Expansion für die 24-Bit-Schnittstelle aufgelöst.
Das Objekt ist nur im 24-Bit-Adressierungsmodus ablauffähig.
= 31
Der Makroaufruf wird adressierungsmodus-unabhängig generiert.
PLIST
erzeugt eine Liste mit symbolischen Adressen für den Ein- oder Ausgabebereich, abhängig von den Operanden VERSION und PARMOD.
= INPUT
Liste für den Eingabebereich
= OUTPUT
Liste für den Ausgabebereich
PREFIX
wird nur in Verbindung mit MF=C oder MF=D ausgewertet und legt das jeweils erste Zeichen der Feldnamen und Equates fest, die bei der Makroauflösung im Datenbereich generiert werden.
Voreinstellung: | PREFIX = I |
= pre
Das erste Zeichen der generierten Namen wird durch „pre“ ersetzt;
für den Eingabebereich: 1-2 Zeichen, erstes Zeichen ein Buchstabe;
für den Ausgabebereich: 1 Buchstabe
= *
Es wird kein Präfix generiert.
SHORT
Der statische Teil des TFT-Eintrags und daran anschließend der statische Teil des damit verknüpften TST-Eintrags werden in den Benutzerbereich übertragen (ohne Geräteliste) (siehe Operand LONG).
VERSION
Steuert die Generierung von Operandenliste, SVC und Ausgabebereich. Ein gleichzeitig angegebener PARMOD-Wert wird ignoriert, dabei wird allerdings eine MNOTE-Meldung erzeugt.
Der Returncode wird ausschließlich im Standardheader der Parameterliste abgelegt. Außerdem liefert die RDTFT-Funktion die neue Ausgabeliste (siehe „Hinweise zur Programmierung").
Voreinstellung: | Die Generierung der Operandenliste wird durch den Operanden PARMOD gesteuert. |
= 2
erzeugt die ab BS2000 V9.5 gültige Operandenliste. Der Returncode wird im Standardheader und in Register 15 abgelegt.
= 3
bezeichnet die Makroversion: es wird die Operandenliste für die ab BS2000/OSD-BC V3.0 gültige Makroversion generiert.
Hinweise zur Programmierung
Eingabebereich
Ohne den Operanden VERSION wird die bisherige Operandenliste generiert – abhängig vom Operanden PARMOD. Eine DSECT für diesen Bereich kann generiert werden mit dem Makroaufruf DMARD oder mit den Operanden MF=D,PLIST=INPUT des RDTFT-Makroaufrufs.
Bei Angabe von VERSION=2/3 enthält die Operandenliste den Standardheader. Außerdem ist das Feld zur Aufnahme der Länge des Ausgabebereichs als Adresskonstante (4 Byte) definiert. Eine DSECT für diesen Bereich wird mit den Operanden VERSION=2/3, MF=D, PLIST=INPUT erzeugt.
Ausgabebereich
Der RDTFT-Makroaufruf stellt – je nach Verwendung des LINK-Operanden – zwei Ausgabelisten zur Verfügung:
ohne LINK=name oder falls „name“ Wildcards enthält und der Operand LINKWC=YES gesetzt ist, wird nur eine Liste der Dateikettungsnamen und der damit verknüpften Dateinamen in den Ausgabebereich übertragen.
Die Liste wird in chronologischer Reihenfolge ausgegeben; d.h. der Dateikettungsname des zuerst erstellten TFT-Eintrags wird an erster Stelle übertragen. Jedem Paar LINK-Name/Dateiname wird ein Byte vorangestellt, das die Länge dieser beiden Felder + 1 angibt. Die Liste wird abgeschlossen mit einem Byte, das den Wert X'00' enthält. Das Folgebyte zeigt an, ob alle Informationen in den Benutzerbereich übertragen werden konnten:
X'00' Alle Dateikettungsnamen und deren Dateinamen sind in den Benutzerbereich übertragen worden. X'01' Ein oder mehrere Dateikettungsnamen, samt Dateinamen, konnten nicht in den bereits gefüllten Benutzerbereich übertragen werden. Ist NUMONLY=YES spezifiziert, wird in den ersten vier Byte des Ausgabebereichs die Anzahl der selektierten TFT-Einträge ausgegeben. Eine weitere Ausgabe erfolgt nicht.
- mit LINK=name werden TFT- und TST-Informationen für den angegebenen Dateikettungsnamen ausgegeben, sofern „name“ keine Wildcards enthält.
Der Ausgabebereich gliedert sich dann in einen festen und einen variablen Teil: der feste Teil enthält Informationen aus TFT und TST, der variable Teil wird nur aufgebaut, wenn der Operand LONG angegeben wurde; er enthält weitere Informationen aus der TFT und evtl. TST-Datenträger-Informationen.
Feldlänge (Byte) mit VERSION | Feldlänge (Byte) ohne VERSION | Inhalt |
2 | 2 | Länge des Ausgabebereichs ohne variablen Teil |
8 | 8 | Dateikettungsname |
54 | 54 | Pfadname |
116 | 76 | statischer Teil des TFT-Eintrags und des damit verbundenen TST-Eintrags |
variabel | variabel | TFT- und TST-Datenträgerinformationen (bei Angabe von LONG) |
Ohne den Operanden VERSION wird die Ausgabeliste im bisherigen Format erzeugt. Mit dem Makroaufruf DMADR oder den Operanden MF=D, PLIST=OUTPUT des RDTFT-Makroaufrufs kann eine DSECT für diese Ausgabeliste erzeugt werden.
Mit dem Operanden VERSION=2/3 wird die neue Ausgabeliste erzeugt, die gegenüber der bisherigen um einige Felder erweitert wurde. Insbesondere stellt die neue Ausgabeliste zusätzlich zur bisherigen Informationen über BLKCTRL, POOLLNK, TAPEWR, CLOSMSG, CLOSE, IOPERF, IOUSAGE, EXC32GB und DESTOC (siehe FILE-Makro, "FILE - Dateimerkmale definieren/Dateiverarbeitung steuern") zur Verfügung. Außerdem wird der Gerätetyp in abdruckbarer Form (z.B. „D3439-10“) ausgegeben. Für die Ausgabe mit LONG wurde die TFT-Datenträger-Information erweitert. Eine DSECT für die Ausgabeliste kann mit den Operanden VERSION=2/3, MF=D, PLIST=OUTPUT erzeugt werden.
Bei PARMOD=31 oder VERSION=2/3 wird der Pfadname stets vollständig ausgegeben, andernfalls in der Form, in der er über den FILE- oder OPEN-Makro in den TFT-Eintrag gebracht wurde, d.h. gegebenenfalls ohne Katalog- oder Benutzerkennung. Systemspezifisch kann jedoch festgelegt werden, dass Katalog- und Benutzerkennung immer ausgegeben werden.
Ist der TFT-Eintrag nicht mit einem TST-Eintrag verknüpft, wird der entsprechende Teil des Ausgabebereiches auf binär null (X'00') gesetzt.
Returncodes
Der Fehlercode wird im Standardheader des Parameterbereichs zurückgegeben. Fehlercode 0 bedeutet, dass kein Fehler aufgetreten ist. Die anderen Fehlercodes sind im Makro DMAIDEM bzw. DCOIDEM beschrieben.
Eine Programm-Terminierung mit STXIT-Anschluss kann in folgenden Fällen eingeleitet werden:
Parameteradresse fehlerhaft (z.B. kürzer als der Standardheader)
Parameteradresse nicht wort-ausgerichtet
UNIT oder FUNCTION im Header fehlerhaft
Header nicht beschreibbar
Ist die Versionsangabe fehlerhaft, wird der Returncode im Header und in Register 15 zurückgeliefert. Ist der Header nicht beschreibbar, erfolgt Programm-Terminierung mit STXIT-Anschluss. Die Subcodes werden nur ab VERSION=3 versorgt.
Standardheader: ccbbaaaa
Über die Ausführung des Makros RDTFT wird im Standardheader folgender Returncode übergeben (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'cc' | X'bb' | X'aaaa' | Erläuterung |
X'01' | X'059D' | Ungültiger Linkname | |
X'01' | X'05AB' | Ungültiger Bereich oder Länge | |
X'40' | X'05E1' | Linkname nicht gefunden | |
X'01' | X'06CB' | Ausgabebereich zu klein | |
X'01' | X'06FD' | Ungültiger Parameterlisten-Bereich | |
X'03' | X'FFFF' | Ungültige Version |
Beispiel
BEGIN START
.
.
RDTFT MF=(E,BEREICH),VERSION=3 RDTFT-SVC
.
.
BEREICH RDTFT AUSGABE,,SHORT,LINK=OTTO,MF=L,VERSION=3 OPERANDENLISTE
.
.
AUSGABE DS XL180 AUSGABEBEREICH
.
EINPL RDTFT MF=D,PLIST=INPUT,VERSION=3 DSECT EINGABE-OPER-LISTE
.
AUSPL RDTFT MF=D,PLIST=OUTPUT,VERSION=3 DSECT AUSGABE-OPER-LISTE
.
.
END