Das Benutzerprogramm muss beim Aufruf der MARENADM-Programmschnittstelle MAREN1PS drei Speicherbereiche für die Datenübergabe bereitstellen:
Anweisungsbereich (maximal 1014 Bytes)
Das Benutzerprogramm muss hier eine MARENADM-Anweisung als Satz variabler Länge (4 Bytes langes Satzlängenfeld) im üblichen BS2000-Format bereitstellen. Die Anweisung kann mit oder ohne die beiden Schrägstriche gebildet werden. Der Anweisungsbereich muss auf Halbwortgrenze ausgerichtet sein.
Katalogeintragsbereich (1014 Bytes)
In diesem Bereich übergibt MAREN an das Benutzerprogramm je nach Anweisung entweder einen kompletten Katalogeintrag oder nur die Katalogeintragsfelder RETFLAG und ERRORKEY. Die einzelnen Katalogeintragsfelder können über die Dsect MARENA bzw. das Copyelement MARENAC symbolisch adressiert werden.
Der Katalogeintrag wird im V8-Format (1014 Bytes) zurückgeliefert (der Sekundärindexbereich eines Katalogs im V8.1-Format wird an der Programmschnittstelle nicht unterstützt.
Parametersatzbereich (672 Bytes)
In diesem Bereich erhält das Benutzerprogramm nach der Anweisung SHOW-MAREN-PARAMETERS den kompletten Parametersatz. Die einzelnen Katalogeintragsfelder können über die Dsect MARENP bzw. das Copyelement MARENPL symbolisch adressiert werden. Dieser Bereich muss auch bei jeder anderen Anweisung bereitgestellt werden, da er intern von MAREN1PS als Arbeitsbereich benötigt wird.
Beim Aufruf der Programmschnittstelle ist der Inhalt des Katalogeintrags- und des Parametersatzbereiches ohne Bedeutung.
Der Makro MARENA generiert eine DSECT zur symbolischen Adressierung der einzelnen Katalogeintragsfelder. Der Makro MARENP generiert eine DSECT zur symbolischen Adressierung der einzelnen Felder des MAREN-Parametersatzes. Beide Makros (MARENA und MARENP) sind in der Bibliothek SYSLIB.MAREN.<ver> enthalten. Wird im Makroaufruf der Operand MF=L angegeben, so wird jeweils ein Datenbereich in der Länge des Katalogeintrags bzw. des Parametersatzes mit zu den Namen in der jeweiligen Dsect identischen Feldbezeichnungen angelegt.
Mit der Übersetzungsanweisung COPY kann das Source-Element MARENAC in ein CO-BOL-Quellprogramm eingebracht werden. MARENAC definiert den MAREN-Katalogeintrag. Mit der Übersetzungsanweisung COPY kann das Source-Element MARENPC in ein COBOL-Quellprogramm eingebracht werden. MARENPC definiert den MAREN-Parametersatz. Auch die beiden Copyelemente (MARENAC und MARENPL) sind in der Bibliothek SYSLIB.MAREN.<ver> enthalten.
Nach der Ausführung einer Anweisung kehrt MAREN1PS automatisch wieder zum Benutzerprogramm zurück. Die Anweisung RETURN-TO-PROGRAM ist hier also überflüssig. Die Anweisung END schließt die MAREN-Dateien, falls diese im Direktzugriff geöffnet waren.
Die Angabe eines Nummernkreises bei einigen Anweisungen (Operand VOLUME= *INTERVAL(FROM=..., TO=...)) ist auch bei der Programmschnittstelle zulässig. Allerdings wird nur der erste zutreffende Katalogeintrag bearbeitet und danach sofort zum Aufrufer zurückgekehrt. Gegebenenfalls muss das Benutzerprogramm die Anweisung in einer Schleife wiederholen und dabei jedes Mal den Nummernkreisanfang (FROM-Operand und FROM-FSEQ-Operand) auf die zuletzt erhaltene Archivnummer setzen und die FSEQ erhöhen. Bei der Erhöhung der FSEQ ist Folgendes zu beachten: falls pro Archivnummer nur ein Katalogeintrag verarbeitet werden soll, muss die FSEQ auf 9999 gesetzt werden. Falls dagegen zu jeder Archivnummer alle vorhandenen FSEQ-Einträge verarbeitet werden sollen, muss die FSEQ um eins erhöht werden, außer bei FSEQ=*001 (siehe Beispiel auf "Beispiele").
Rückkehrinformation
Nach jeder Rückkehr aus der MARENADM-Programmschnittstelle MAREN1PS muss das Benutzerprogramm die Rückkehrinformation im Katalogeintragsfeld RETFLAG kontrollieren. Nur bei RETFLAG=A wurde die Anweisung ordnungsgemäß ausgeführt. RETFLAG=E bedeutet, dass im angegebenen Nummernkreis kein Treffer erzielt wurde. Bei allen anderen RETFLAGs muss eine weitere Rückkehrinformation im Katalogeintragsfeld ERRORKEY ausgewertet werden. Dort wird der siebenstellige Meldungsschlüssel derjenigen Meldung übergeben, die sonst vom MARENADM-Programm auf SYSOUT ausgegeben wird.
Folgende Werte können für RETFLAG eingetragen sein:
RETFLAG | Bedeutung |
A | Anweisung fehlerfrei ausgeführt. |
D | Beim Zugriff auf eine Datei ist ein DVS-Fehler aufgetreten. Der Name der betroffenen Datei steht im Katalogeintragsfeld FILENAME. Der DVS-Fehlercode steht im Katalogeintragsfeld ERRORKEY. |
E | Im angegebenen Nummernkreis wurde kein Treffer erzielt. |
I | Ungültige Eingabe. |
L | Logischer Fehler, z.B.: soll ein bereits ausgeliehenes Band ausgeliehen werden. |
M | Interner Fehler in MAREN; die genaue Fehlerursache steht im Katalogeintragsfeld ERRORKEY. |
N | Die angegebene Archivnummer existiert im MAREN-Katalog nicht. |
O | Der MAREN-Administrator hat Offline-Logging eingeschaltet; Zugriffe auf den MAREN-Katalog sind somit nicht möglich. |
P | Der Katalogeintrag wurde gleichzeitig von einer anderen Task verändert; diese Anweisung muss daher wiederholt werden. |
S | Der Zugriff auf ein anderes System über MSCF war nicht erfolgreich. |
T | Das Band ist noch von einer anderen Task des eigenen Systems belegt. |
V | Das Band wurde von einer Task eines anderen Systems noch nicht wieder freigegeben, d.h. die MAREN-interne Zugriffssperre für dieses Band besteht noch. |
X | Anforderung wurde vom MAREN-Administrator mittels einer Exit-Routine abgewiesen. |
0 | Die Konsolmeldung |
2 | Die Konsolmeldung |
Beim Unterprogrammaufruf müssen die folgenden Register geladen werden:
Register 1: | enthält die Adresse einer drei Worte langen Operandenliste: |
Register 13: | enthält die Adresse eines Sicherstellungsbereiches von 18 Worten, der vom aufrufenden Benutzerprogramm zur Verfügung gestellt werden muss. |
Register 14: | enthält die Adresse des Rückkehrpunktes ins aufrufende Programm. |
Register 15: | enthält die Einsprungadresse von MAREN1PS. |