DSPSRV - Datenraum verwalten

Allgemeines

Anwendungsgebiet:	Erweiterung durch Datenräume; siehe "Erweiterung durch Datenräume"
Makrotyp:	S-Typ, MF-Format 3: C-/D-/L-/M-/R-/E-Form; siehe "S-Typ-Makroaufrufe"

Anwendungsgebiet: Erweiterung durch Datenräume; siehe "Erweiterung durch Datenräume"

Makrotyp: S-Typ, MF-Format 3: C-/D-/L-/M-/R-/E-Form; siehe "S-Typ-Makroaufrufe"

Der Makro DSPSRV kann auf allen BS2000-Servern verwendet werden (siehe Abschnitt „Erweiterung durch Datenräume“).

Makrobeschreibung

Mit dem Makro DSPSRV kann der Anwender unter Angabe des Typs, eines Namens, eines Geltungsbereiches und der gewünschten Größe einen Datenraum anlegen. Damit wird dieser Anwender zum Eigentümer des Datenraumes. Das System gibt eine Identifikation zurück (die SPID), die den Datenraum sessionweit eindeutig kennzeichnet.
Um auf einen Datenraum zugreifen zu können, muss das Programm mit ihm über Zugriffslisten verbunden werden. Diese Verbindung wird durch den Makro ALESRV realisiert.

Der Datenraum-Typ bestimmt die Art der Allokierung/Deallokierung des Speichers innerhalb des Datenraums und die Funktionen, die dazu zur Verfügung stehen.

Die Funktionen des DSPSRV-Makros ermöglichen:

• einen Datenraum anzulegen (FCT=CREATE),

• einen bestehenden Datenraum wieder freizugeben (FCT=DESTROY),

• Informationen über einen bestehenden Datenraum abzufragen (FCT=INFORM),

für einen Datenraum vom Typ STACK:

• einen bestehenden Datenraum um Speicherseiten zu erweitern (FCT=EXTEND),

• den Inhalt eines bestehenden Datenraumes (auch teilweise in 4KB-Einheiten) zu löschen, d.h. mit binären Nullen zu überschreiben (FCT=CLEAR),

• die aktuelle Größe eines Datenraums zu verringern (FCT=REDUCE),

für einen Datenraum vom Typ HEAP:

• einen Bereich für einen Datenraum anzufordern (FCT=GETAREA) und

• einen Bereich für einen Datenraum freizugeben (FCT=RETAREA).

Makroaufrufformat und Operandenbeschreibung

DSPSRV

FCT=

{ CREATE,NAME='name' / name_adr
        ,INISIZE=zahl / (r)
        ,MAXSIZE=zahl / (r)
        ,DIAPROT=NO / YES
        ,SCOPE=LOCAL / GROUP / USER_GROUP / GLOBAL
        ,TYPE=STACK / HEAP                              |

  DESTROY,SPID=spid_adr                                 |

  INFORM,IDENT=NAME / SPID
       [,SPID=spid_adr]
       [,NAME='name' / name_adr]
        ,SCOPE={LOCAL / GROUP / USER_GROUP / GLOBAL}    |

  EXTEND,SPID=spid_adr
        ,SIZE={zahl / (r)}                              |

  CLEAR,SPID=spid_adr
        ,AREA=area_adr / (r)
        ,SIZE=zahl / (r)                                |

  REDUCE,SPID=spid_adr
        ,SIZE=zahl / (r)                                |

  GETAREA,SPID=spid_adr
        ,SIZE=zahl / (r)                                |

  RETAREA,SPID=spid_adr
        ,AREA=area_adr / (r)
        ,SIZE=zahl / (r)
}

[ ,MF=C / D / L / M / E / R
  [,SPID=spid_adr]
  [,EXTADDR=ext_adr]
  [,AREA=area_adr]]
]

[,PARAM=adr / (r)]

,PREFIX=N / p

,MACID=VDD / macid

In der folgenden Operandenbeschreibung sind die Operanden alphabetisch geordnet.

AREA=
legt die Startadresse eines Datenraumbereiches fest. Dieser Operand kann sowohl Eingabeoperand (FCT=RETAREA, CLEAR) als auch Ausgabeoperand (FCT=GETAREA) sein.
Die Adresse muss auf Seitengrenze (4KB) ausgerichtet werden und im Bereich des angelegten Datenraumes liegen.

area_adr
symbolische Adresse (Name) eines Feldes (4 Byte), das die Startadresse des Bereiches enthält.

(r)
r = Register, dessen Inhalt die Startadresse ist.

DIAPROT=
gibt an, ob der Datenraum gegen Zugriffe durch Diagnose-Tools (z.B. AID, USERDUMP, CDUMP2) geschützt werden soll.

NO
Der Datenraum wird nicht geschützt, d.h. Zugriffe durch Diagnose-Tools sind erlaubt.

YES
Der Datenraum soll besonders geschützt werden. Zugriffe durch Diagnose-Tools werden nicht erlaubt.

EXTADDR=
legt die Startadresse des zu erweiterenden Datenraums fest. Dieser Operand ist ein Ausgabeoperand (nur bei MF=R).

ext_addr
Adresse zur Ausgabe der Startadresse der neuen Speicherplatzerweiterung (bei FCT=EXTEND).

FCT=
bestimmt die auszuführende Funktion des Makros DSPSRV.

CREATE
legt eine neuen Datenraum an. Der Aufrufer wird der Eigentümer des Datenraumes.Das System gibt bei Returncode X'aaaa'=X'0000' die SPID zurück, die mit MF=R aus dem Datenbereich gelesen werden kann.

DESTROY
gibt einen bestehenden Datenraum wieder frei, sofern der Aufrufer auch der Eigentümer des Datenraumes ist.

EXTEND
erweitert einen bestehenden Datenraum vom Typ STACK um Speicherseiten zu je 4KB. Zur Größe des Datenraums siehe Hinweise zur Adressraumgröße.
Das System gibt bei Returncode X'aaaa'=X'0000' die Startadresse der Speicherplatzerweiterung (EXTADDR) zurück, die mit MF=R aus dem Datenbereich gelesen werden kann. Der allokierte Bereich wird mit binären Nullen überschrieben.

CLEAR
löscht Inhalte eines Datenraumbereiches vom Typ STACK, indem Speicherseiten in Einheiten zu je 4KB mit binären Nullen überschrieben werden. Die so gelöschten Speicherseiten bleiben nicht länger im realen Speicher (Seitenwechselspeicher) erhalten.

INFORM
informiert über den mit seinem Namen und Geltungsbereich oder seiner SPID angegebenen Datenraum. Die mit MF=D generierte DSECT beinhaltet alle Informationen.

REDUCE
verringert die aktuelle Größe eines Datenraums vom Typ STACK um Speicherseiten zu je 4 KB.

GETAREA
weist einen allokierten Bereich innerhalb eines Datenraums vom Typ HEAP zu.
Das System gibt bei Returncode X'aaaa'=X'0000' die Startadresse des Bereichs (AREA) zurück, die mit MF=R aus dem Datenbereich gelesen werden kann. Der allokierte Bereich wird mit binären Nullen überschrieben.

RETAREA
gibt einen allokierten Bereich innerhalb eines Datenraums vom Typ HEAP frei.

IDENT=
bestimmt, durch welche Operanden (NAME und SCOPE oder SPID) der Datenraum identifiziert werden soll (bei FCT=INFORM).

NAME
Der Datenraum wird durch Angabe seines Namens und seines Geltungsbereiches identifiziert.

SPID
Der Datenraum wird durch die Angabe seiner SPID identifiziert.

INISIZE=
gibt die Anfangsgröße des angeforderten Datenraumes in Einheiten zu je 4KB an. Zur Größe des Datenraums siehe Hinweise zur Adressraumgröße und zur Allokierungsgröße (siehe "DSPSRV - Datenraum verwalten").

zahl
positiver, ganzzahliger Wert (X'01' .. X'80000'), der die Anfangsgröße des Datenraums angibt.

(r)
r = Register, dessen Inhalt zahl ist.

MAXSIZE=
gibt die gewünschte maximale Größe des angeforderten Datenraumes in Einheiten zu je 4KB an. Für einen Datenraum vom Typ HEAP wird die angegebene Größe auf die nächste MB-Grenze aufgerundet.
Ein Datenraum muss seine angegebene maximale Größe nicht erreichen, sie stellt nur eine Begrenzung nach oben dar. Die maximal zulässige Größe ist abhängig von der im Benutzerkatalog angegebenen maximal erlaubten Adressraumgröße (ADDRESS-SPACE-LIMIT), siehe Hinweise zur Adressraumgröße.

zahl
positiver, ganzzahliger Wert (X'01' .. X'80000'), der die maximale Größe des Datenraums angibt.

(r)
r = Register, dessen Inhalt zahl ist.

MF=
Zur allgemeinen Beschreibung des Operanden MF, der dazugehörenden Operandenwerte und der evtl. nachfolgenden Operanden (z.B. PREFIX, MACID und PARAM) siehe Abschnitt „S-Typ-Makroaufrufe“. Die gültigen MF-Werte sind zu Beginn der Makrobeschreibung bei „Makrotyp“ angegeben und aus dem Aufrufformat ersichtlich.

Bei der C-Form, D-Form, R-Form oder M-Form des Makroaufrufs kann ein Präfix PREFIX und bei der C-Form, R-Form oder M-Form zusätzlich eine Macid MACID angegeben werden (siehe Abschnitt „S-Typ-Makroaufrufe“).

Mit MF=R können die Ausgabeparameter der Funktionen CREATE (SPID=), INFORM (SPID=), EXTEND (EXTADDR=) und GETAREA (AREA=) aus dem Parameterbereich ausgelesen werden.

NAME=
benennt den Datenraum. Länge = 1..54 alphanumerische Zeichen, wobei das erste Zeichen ein Buchstabe oder eines der Zeichen # oder @ sein muss.
Der Name eines Datenraumes ist nur innerhalb seines Geltungsbereiches (siehe Operand SCOPE) eindeutig, d.h. dass Datenräume mit gleichem Namen, aber unterschiedlichen Geltungsbereichen gleichzeitig existieren können.

'name'
name = Name des Datenraumes.

name_adr
symbolische Adresse (Name) eines Feldes (54 Bytes), das den Namen des Datenraumes in alphanumerischen Zeichen enthält.

SCOPE=
bestimmt den Geltungsbereich des angegebenen Datenraumes. Ein Datenraum ist nur innerhalb seines Geltungsbereiches eindeutig durch seinen Namen gekennzeichnet.
Der Geltungsbereich bestimmt, welche Tasks am angegebenen Datenraum teilhaben, auf ihn zugreifen können.

LOCAL
Der Datenraum wird nur von der einrichtenden Task genutzt. Andere Tasks haben keinen Zugriff.

GROUP
Alle Tasks mit der Benutzerkennung der einrichtenden Task können sich an den Datenraum anschließen.

USER_GROUP
Alle Tasks, deren Benutzerkennung derselben Benutzergruppe angehören wie die Benutzerkennung der einrichtenden Task, können den Datenraum nutzen.
Voraussetzung ist, dass das Subsystem SRPMOPT geladen wurde.

GLOBAL
Alle Tasks im laufenden System können sich an den Datenraum anschließen.

SIZE=
legt die Größe des Bereichs bei den Funktionen EXTEND, REDUCE, CLEAR, GETAREA und RETAREA fest. Dieser Operand wird in Einheiten zu je 4KB angegeben.
Zu beachten ist:

• bei FCT=EXTEND:
  Der um SIZE erweiterte Datenraum darf nicht größer werden, als bei MAXSIZE angegeben ist, siehe Hinweise zur Adressraumgröße auf "DSPSRV - Datenraum verwalten".

• bei FCT=CLEAR/RETAREA:
  Der durch AREA und SIZE bestimmte Bereich muss innerhalb des Datenraumes liegen, der durch SPID bestimmt ist.

• bei FCT=REDUCE:
  Der Wert von SIZE darf nicht größer als die aktuelle Größe des Datenraums sein.

• bei FCT=GETAREA:
  Die Summe aller allokierten Bereiche darf nicht größer werden als bei MAXSIZE angegeben.

  zahl
  positiver, ganzzahliger Wert >= 1, der die Anzahl der Einheiten zu je 4KB bestimmt, um die der Datenraum erweitert werden soll (FCT=EXTEND) bzw. die gelöscht werden sollen (FCT=CLEAR).

  (r)
  r = Register, dessen Inhalt zahl ist.

SPID=
kennzeichnet einen Datenraum eindeutig im Gesamtsystem.
Sie wird beim Anlegen eines Datenraumes vom System vergeben.
Dieser Operand kann sowohl Ein- als auch Ausgabeoperand sein.

spid_adr
symbolische Adresse (Name) eines Feldes (8 Byte), das die SPID des Datenraumes enthält.

TYPE=
bestimmt die Art der Allokierung/Deallokierung des Speichers innerhalb des Datenraums. Er wird zum Zeitpunkt der Erzeugung bestimmt.

STACK
Ein Datenraum vom Typ STACK ist ein virtuell zusammenhängender allokierter Bereich, beginnend ab Adresse 0 bis zur aktuellen Größe.
Die verfügbaren Allokierungsfunktionen sind EXTEND, REDUCE und CLEAR. Die Funktionen GETAREA und RETAREA werden abgewiesen.

HEAP
Ein Datenraum vom Typ HEAP ist ein virtueller Adressraum, in dem dynamisch beliebig große Bereiche bis zur maximalen Größe des Datenraums allokiert werden können. Die verfügbaren Allokierungsfunktionen sind GETAREA und RETAREA. Die Funktionen EXTEND, REDUCE und CLEAR und der Parameter INISIZE werden abgewiesen.

Hinweis

DIV (Data in Virtual)-Funktionalität wird nur in Datenräumen vom Typ STACK unterstützt.

Hinweise zum Makroaufruf

• Der Operand SPID kann sowohl Ein- als auch Ausgabeoperand sein, d.h. dass er durch FCT=CREATE oder FCT=INFORM in dem erzeugten Datenbereich als Ausgabeoperand vorliegt und bei nochmaliger Verwendung dieses Datenbereichs auch als Eingabeoperand gültig ist. Dasselbe gilt für den Operand AREA bei den Funktionen GETAREA und RETAREA.

• Die Summe der von der Task schon belegten und durch den Makro DSPSRV zusätzlich angeforderten Speicherseiten darf die im Benutzerkatalog eingetragene maximale Größe des Adressraums (ADDRESS-SPACE-LIMIT) des Eigentümers nicht überschreiten. Dasselbe gilt für die Angabe von MAXSIZE.
  Mit dem Kommando SHOW-USER-ATTRIBUTES PUBSET=*HOME kann sich der Anwender über seine Adressraumgröße informieren. Ist die Adressraumgröße ausgeschöpft, wird ein Speicherplatzfehler gemeldet und die Funktion abgebrochen.

• Bei Beendigung des Programms, das den Datenraum erzeugt hat, wird der Datenraum automatisch, d.h. auch ohne FCT=DESTROY, freigegeben. Die SPID verliert ihre Gültigkeit, noch bestehende ALETs werden jedoch nicht gelöscht. Greift ein anderes Programm mit einem solchen ALET auf den nicht mehr existierenden Datenraum zu, wird es abgebrochen.

• Wenn in einem zu löschenden Datenraum noch DIV-Fenster existieren, so müssen diese vor der Freigabe geschlossen werden.

Hinweise zur Adressraumgröße

• Die im Benutzerkatalog angegebene maximale Adressraumgröße darf von keiner Angabe zum Erzeugen oder Erweitern von Datenräumen überschritten werden. Das bedeutet, dass die Summe aller Speicheranforderungen kleiner/gleich der im Feld ADDRESS-SPACE-LIMIT stehenden Adressraumgröße sein muss. Die Summe aller Speicheranforderungen ergibt sich aus:

  • den im Programmraum allokierten Klasse-6-Speicherseiten,

  • den allokierten Seiten, die für bereits erzeugte Datenräume angefordert wurden,

  • den mit dem aktuellen DSPSRV-Aufruf angeforderten Seiten (mit INISIZE und MAXSIZE beim Erzeugen oder mit SIZE beim Erweitern).

• Die für einen Datenraum beim Erzeugen angegebene maximale Größe (MAXSIZE) muss größer oder gleich der bei INISIZE angegebenen Anfangsgröße des Datenraums sein.
  Die beim Erweitern eines Datenraums anzugebende Größe SIZE darf (zusammen mit INISIZE und evtl. schon vorher mit FCT=EXTEND hinzugefügten Speicherseiten) MAXSIZE nicht überschreiten.

Rückinformation und Fehleranzeigen

Standardheader:

+---------------+
|   |   |   |   |
|c|c|b|b|a|a|a|a|
+---------------+

Über die Ausführung des Makros DSPSRV wird im Standardheader ein Returncode übergeben (cc=Subcode2, bb=Subcode1, aaaa=Maincode):

X'cc'	X'bb'	X'aaaa'	Erläuterung
X'00'	X'00'	X'0000'	Funktion erfolgreich ausgeführt. Mit MF=R kann aus dem Datenbereich folgender Wert gelesen werden: bei FCT=CREATE: spid_adr (Operand SPID) bei FCT=EXTEND: ext_adr (Operand EXTADDR) bei FCT=INFORM: spid_adr (Operand SPID) bei FCT=GETAREA: area_adr (Operand AREA)
X'02'	X'00'	X'0001'	Warnung: Der angegebene Datenraum wurde freigegeben, obwohl noch andere Programme mit ihm verbunden sind (bei FCT=DESTROY).
X'00'	X'01'	X'0003'	Ungültiger Operand FCT.
X'01'	X'01'	X'0003'	Ungültiger Operand NAME.
X'02'	X'01'	X'0003'	Ungültiger Operand SCOPE.
X'04'	X'01'	X'0003'	Ungültiger Operand TYPE.
X'05'	X'01'	X'0003'	Ungültiger Operand IDENT.
X'06'	X'01'	X'0003'	Ungültiger Operand MAXSIZE.
X'07'	X'01'	X'0003'	Ungültiger Operand INISIZE.
X'0A'	X'01'	X'0003'	Ungültiger Operand DIAPROT.
X'0C'	X'01'	X'0003'	Ungültiger Operand AREA.
X'0D'	X'01'	X'0003'	Ungültiger Operand SIZE.
X'FF'	X'01'	X'0003'	Ungültige Kombination von Operanden.
	X'20'	X'0005'	Interner Fehler.
X'00'	X'40'	X'000D'	DIV-Anwendung läuft: Der Datenraum enthält DIV-Fenster (bei FCT=DESTROY).
X'00'	X'40'	X'0102'	Die Angabe des Operanden NAME ist fehlerhaft. Es existiert bereits ein Datenraum mit dem angegebenen Namen (nur bei FCT=CREATE).
X'00'	X'40'	X'0104'	Ungültige Angabe von NAME und/oder SCOPE (bei FCT=INFORM).
X'00'	X'40'	X'0106'	Max. Seitenwechselspeicher-Auslastung erreicht.
X'00'	X'40'	X'0107'	Der im Benutzerkatalog eingetragene maximale Adressraum für die Task (ADDRESS-SPACE-LIMIT) wurde überschritten. Ungültige Angabe von INISIZE oder MAXSIZE (bei FCT=CREATE) oder SIZE (bei FCT=EXTEND).
X'00'	X'40'	X'0202'	Fehler bei SCOPE=USER_GROUP: Das Subsystem SRPMOPT ist nicht geladen (bei FCT=CREATE).
X'00'	X'40'	X'0206'	Max. Hauptspeicher-Auslastung erreicht.
X'00'	X'40'	X'0302'	Die aufrufende Task ist nicht der Eigentümer des Datenraumes und darf diesen nicht löschen (bei FCT=DESTROY).
X'00'	X'40'	X'0304'	Die Angabe des SPID-Operanden ist fehlerhaft: Der angegebene Datenraum existiert nicht oder der Aufrufer hat keine Berechtigung, auf diesen Datenraum zuzugreifen.
X'00'	X'40'	X'0306'	Max. erlaubte Anzahl von Datenräumen erreicht (FCT=CREATE).
X'00'	X'40'	X'0404'	Fehler bei TYPE. Der Typ des Datenraums ist für die angegebene Funktion ungültig.
X'00'	X'40'	X'0406'	Adressraum-Sättigung. Nicht genügend freier und zusammenhängender Adressraum innerhalb des Datenraums vorhanden, um die Anforderung zu erfüllen (bei FCT=GETAREA)
X'00'	X'40'	X'0604'	Ungültiger Operand (MAX)SIZE: Die max. Größe des Datenraumes wird überschritten (bei FCT=EXTEND). Die angegebene Größe liegt über der aktuellen Größe des Datenraums (bei FCT=REDUCE). Die angegebene Größe liegt über der maximalen Größe des Datenraums (bei FCT=GETAREA)
X'00'	X'40'	X'0C04'	Der angegebene Bereich ist nicht Bestandteil des Datenraumes (bei FCT=CLEAR und FCT=RETAREA).
X'00'	X'40'	X'0F04'	Allokierungsfehler. Der angegebene Bereich ist nicht innerhalb des Datenraums allokiert (bei FCT=RETAREA).
X'00'	X'81'	X'0106'	Max. Seitenwechselspeicher-Auslastung erreicht.
X'00'	X'81'	X'0306'	Interner Ressourcen-Engpass.

Weitere Returncodes, deren Bedeutung durch Konvention makroübergreifend festgelegt ist, können der Tabelle „Standard-Returncodes“ (Standardheader) entnommen werden.

Beispiel siehe im Abschnitt „Erweiterung durch Datenräume“.