PAM - UPAM-Aktionen ausführen

Makrotyp: S-Typ

Alle Benutzeranforderungen an das DVS bezüglich UPAM-Aktionen werden über diesen Makroaufruf abgewickelt.

Format

Operation	Operanden
PAM	fcbadr [,PARMOD = 24 / 31] [,RDWT / CHK / LOCK / LRD / LRDWT / RD / RDEQU / SETL /   SETLPP / SYNC / UNLOCK / WRT / WRTWT / WRTWU / WT] [,CHAIN = relaus][,FECB = relaus][,HP = zahl / +zahl / -zahl] ,KEYFLD = relaus] [,LEN = STD / (STD,n) / länge] [,LOC = 1 / 2 / relaus] [,MKEY = NO / YES] [,REQNO = zahl] [,POST = postcode]

Operandenbeschreibung

fcbadr

Gibt die Adresse des FCB an, der mit dieser Datei in Verbindung steht.

CHAIN = relaus

Bezeichnet die symbolische Adresse des nächsten Elements einer Kette von PAM-Makroaufrufen in Listenform. Eine solche Kette kann höchstens 255 Elemente enthalten.

Voreinstellung:

die Liste wird als das letzte Element einer Kette betrachtet

CHK

Prüft, ob die angegebene Ein-/Ausgabe-Anforderung abgeschlossen ist. Ist dies der Fall, läuft das Programm weiter. Andernfalls wird die Steuerung an die Adresse übergeben, die im Anwenderprogramm unter dem LOC-Operanden angegeben ist.

FECB = relaus

Symbolische Adresse eines Ereignissteuerblocks (siehe "TU-Eventing - ereignisgesteuerte Verarbeitung"). Der Operand darf nur bei den Operationen RD, LRD und WRT angegeben werden.

HP

verweist auf eine PAM-Seite, und zwar

• bei nichtgeketteter Ein-/Ausgabe auf die zu übertragende (oder zu sperrende) PAM-Seite;

• bei geketteter Ein-/Ausgabe (für Plattendateien oder für Banddateien mit Nichtstandardblöcken (NK-Dateien)) auf die Erste einer Reihe zu übertragender (oder zu sperrender) PAM-Seiten.

Voreinstellung:

HP=+1 (d.h. sequenzielle Verarbeitung)

Hinweis

Bei PAM- und SAM-Dateien ohne PAM-Schlüssel (Eigenschaft BLKCTRL=DATA oder BLKCTRL=NO) gelten folgende Einschränkungen, die sich daraus ergeben, dass in diesen Dateien nur auf Logische Datenblöcke und nicht auf jeden 2K-Block zugegriffen werden kann:

• Bei den Operationen LRD, LRDWT, RD, RDWT, RDEQU, WRT, WRTWT, WRTWU, LOCK und UNLOCK muss HP auf den Beginn eines Logischen Blockes zeigen, d.h. HP = n * BLKSIZE + 1 (n >= 0). Andernfalls wird der PAM-Aufruf abgewiesen.

• Bei den Operationen SETL und SETLPP muss HP auf das Ende eines Logischen Blockes zeigen, d.h. HP = n * BLKSIZE (n >= 0). Andernfalls wird der PAM-Aufruf abgewiesen. (Im Fall SETL ist der Dateizeiger damit für den Zugriff auf den nächsten Logischen Block vorbereitet.)

Näheres ist den „Hinweisen zur Programmierung“ am Ende der Beschreibung des PAM-Makroaufrufs auf "PAM - UPAM-Aktionen ausführen" zu entnehmen.

= zahl
logische Nummer der PAM-Seite (LHP) innerhalb der Datei.

= +zahl
= -zahl
Die logische Seitennummer bezieht sich auf den Dateizeiger. Die entsprechende absolute logische Seitennummer wird als Summe von Dateizeiger und angegebener relativer Seitenummer errechnet.

KEYFLD = relaus

Wird nur bei Dateien mit PAM-Schlüssel ausgewertet (Eigenschaft (BLKCTRL=PAMKEY) und bei Dateien mit BLKCTRL=DATA oder BLKCTRL=NO ignoriert.
Der Operand gibt bei nichtgeketteter Ein-/Ausgabe die Adresse eines 16 Byte langen Bereiches an, in den beim Lesen der PAM-Schlüssel gebracht bzw. aus dem beim Schreiben der PAM-Schlüssel gebildet wird.

Bei geketteter Ein-/Ausgabe mit separater Verarbeitung aller zugehörigen PAM-Schlüssel (Operand MKEY=YES) muss hier die Adresse eines genügend großen Bereichs angegeben werden (Anzahl zu übertragender PAM-Seiten mal 16 Byte). Soll nur der PAM-Schlüssel der ersten PAM-Seite verarbeitet werden (MKEY=NO), muss der angegebene Bereich nur 16 Byte lang sein. In diesem Fall kann der Operand KEYFLD entfallen, und es tritt der Standardwert in Kraft.

Der Operand KEYFLD bleibt unberücksichtigt bei den Operationen WT, CHK, SETL und SYNC.
Voreinstellung (bei Dateien mit BLKCTRL=PAMKEY):

• Adresse des ID1KEY1-Feldes im FCB bei allen Lese- und Schreiboperationen außer RDWT, LRDWT und RDEQU

• Adresse des ID1KEY2-Feldes im FCB bei RDWT, LRDWT und RDEQU

Weiteres siehe „Hinweise zur Programmierung".

LEN

Legt die Länge fest, in der bei einem PAM-Aufruf Daten übertragen werden

Voreinstellung:

LEN=STD

Bei den Operationen WT, CHK und SETL wird der Operand LEN nicht berücksichtigt.

Für den Zusammenhang mit der Blocklänge (BLKSIZE) siehe UPAM-FCB-Makroaufruf ("UPAM - User Primary Access Method").

Weiteres siehe „Hinweise zur Programmierung".

= STD
Die Daten werden in der Länge eines Standardblockes (entspricht 2048 Byte) übertragen.

= (STD,n)
Die Daten werden in der Länge von n Standardblöcken (zu je 2048 Byte) übertragen. n ist eine ganze Zahl mit 1 <= n <= 16.
Der Operandenwert kann nur für die 31-Bit-Schnittstelle des Makros angegeben werden.

= länge
Länge der zu übertragenden Daten in Byte (1 <= länge <= 32768). Dabei sind folgende Fälle zu unterscheiden:

• • 1 <= länge <= 2048: keine gekettete Verarbeitung; je PAM-Makroaufruf wird ein Block der Länge 2048 Byte vom/zum Puffer übertragen, d.h. geschrieben oder gelesen.

  • 2049 <= länge <= 32768: gekettete Verarbeitung.

Bei Platten- und Banddateien mit PAM-Schlüssel wird die Anzahl der mit einem PAM-Aufruf zu übertragenden PAM-Blöcke folgendermaßen ermittelt:

• • Ist länge ein ganzzahliges Vielfaches von 2048 (länge = n*2048, n <= 16), gibt der Quotient n = länge/2048 die Anzahl der zu einer Übertragungseinheit gehörenden PAM-Blöcke an.

  • Ist länge kein ganzzahliges Vielfaches von 2048, wird der Quotient auf die nächsthöhere ganze Zahl gerundet. Bei bestimmter Hardware kann eine solche Angabe zur Zwischenpufferung und damit zu Performance-Einbußen führen.

Grundsätzlich wird im Rahmen des CLOSE bei Dateien mit BLKCTRL=PAMKEY die Position des letzten gültigen Bytes im Last Byte Pointer des letzten PAM-Blocks und bei Dateien mit BLKCTRL=NO oder DATA im Last Byte Pointer des letzten logischen Blocks der Datei gespeichert.

Bei Node-Files werden am Dateiende nur die Daten in der Länge länge übertragen. Damit endet ein Node-File bei anschließendem CLOSE auf Byte-Grenze.

Beim Lesen werden die Daten nur in der Länge länge übertragen, beim Schreiben sind sie nur in dieser Länge gültig.

Bei PAM- oder SAM-Plattendateien ohne PAM-Schlüssel wird bei der Ermittlung des Dateizeigers die Länge eines Logischen Datenblockes berücksichtigt; es werden jedoch immer nur so viele Blöcke der Länge 2048 Byte geschrieben, wie es die Angabe im Operanden LEN erfordert.

LOC

Verweist auf den Ein-/Ausgabepuffer im Arbeitsspeicher (gilt nicht für CHK, siehe unter „=relaus“). Der Puffer muss mindestens so viele PAM-Seiten aufnehmen können, wie durch den Operanden LEN= festgelegt ist. Die Pufferadresse kann beliebig auf Bytegrenze ausgerichtet sein. Ist der Puffer <= 4096 Byte (Hauptspeicher-Seite), sollte er in einer Seite enthalten und auf Wortgrenze ausgerichtet sein. Ist dieser Bereich > 4096 Byte, sollte er auf Seitengrenze ausgerichtet sein. Wenn diese Ausrichtung nicht beachtet wird, kann dies bei bestimmter Hardware Zwischenpufferung und damit Performance-Einbuße zur Folge haben. 

Voreinstellung:

• IOAREA2-Adresse im FCB, falls zuvor schon ein PAM-Aufruf für diesen FCB ausgeführt wurde und beim letzten PAM-Aufruf IOAREA1 angegeben wurde.

• IOAREA1-Adresse im FCB in allen anderen Fällen

Der Operand LOC bleibt unberücksichtigt bei den Operationen WT, LOCK, UNLOCK, SETL, SETLPP und SYNC.

= 1
Die Pufferadresse steht im FCB-Feld IOAREA1.

Diese Angabe ist nicht erlaubt, wenn im OPEN-Makro IOAREA1=NO angegeben wurde. Von der (voreingestellten) Möglichkeit des Pufferwechsels darf nur Gebrauch gemacht werden, wenn im OPEN weder IOAREA1=NO noch IOAREA2=NO angegeben wurde.

= 2
Die Pufferadresse steht im FCB-Feld IOAREA2.

Diese Angabe ist nicht erlaubt, wenn im OPEN-Makro IOAREA2=NO angegeben wurde. Von der (voreingestellten) Möglichkeit des Pufferwechsels darf nur Gebrauch gemacht werden, wenn im OPEN weder IOAREA1=NO noch IOAREA2=NO angegeben wurde.

= relaus
Gibt die Pufferadresse bzw. bei CHK die Fortsetzungsadresse an, falls eine geprüfte Ein-/Ausgabe-Anforderung nicht abgeschlossen ist.

Bei der Operation CHK muss „LOC=relaus“ angegeben werden; d.h. eine Adresse, an der der Prozess fortgesetzt werden soll, wenn die geprüfte Ein-/Ausgabeoperation noch nicht abgeschlossen ist.

LOCK

Nur für Plattendateien:
fordert Sperren an für einen oder mehrere PAM-Blöcke (siehe auch Operanden HP, LEN). Sperrung eines Blockes bedeutet, dass andere PAM-Aufrufe mit LOCK oder LRD bzw. LRDWT für diesen Block abgewiesen werden.

LRD

Nur für Plattendateien:
wie LOCK; wurde eine Sperrung erreicht, ist der weitere Verlauf wie bei RD.

LRDWT

Nur für Plattendateien:
wie LOCK und LRD; wurde eine Sperrung erreicht, ist der weitere Verlauf wie bei RDWT.

MKEY

Nur für Plattendateien:
dieser Operand hat nur bei Dateien mit PAM-Schlüssel (Eigenschaft BLKCTRL=PAMKEY) und bei geketteter Ein-/Ausgabe Bedeutung (vgl. auch Operand KEYFLD).

Voreinstellung:

MKEY=NO

= NO
Es wird nur der PAM-Schlüssel der Ersten einer Reihe von PAM-Seiten vom Benutzer erwartet bzw. bereitgestellt.

= YES
PAM-Schlüssel werden vom Benutzer für jede gelesene PAM-Seite erwartet bzw. für jede zu schreibende PAM-Seite bereitgestellt.

PARMOD

Gibt den Generierungsmodus für den Makroaufruf an.

Voreinstellung:

der durch den Makro GPARMOD oder durch den Assembler voreingestellte 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.

POST = postcode

Wird in Zusammenhang mit PARMOD=31 TU-Eventing genutzt, kann der Anwender hier einen POST-Code definieren, ansonsten wird die Angabe eines POST-Wertes ignoriert.

Der POST-Code ist je nach SOLSIG-Definiton bei Beendigung der Ein-/Ausgabe wiederzufinden:

• in den rechten beiden Byte des Feldes RPOSTAD

• in den rechten beiden Byte des bei RPOSTAD angegebenen Registers

• in den rechten beiden Byte des Registers 3 des Contingency-Prozesses, der durch das UPAM-Event gestartet wurde (Näheres siehe Handbuch „Makroaufrufe an den Ablaufteil“ [2], Makro SOLSIG).

RD

Stößt das Lesen eines Datenblocks von der Datei in den Hauptspeicher an; der Auftrag wird unmittelbar nach dem Anstoßen der Leseoperation fortgesetzt.

RDEQU

wie RDWT; bei Plattendateien mit Dual Recording by Volume (DRV, siehe Handbuch „DRV“ [15]) wird zusätzlich die Kopie aktualisiert.
Der Operandenwert kann nur für die 31-Bit-Schnittstelle des Makros angegeben werden.

RDWT

wie RD; der Auftrag läuft jedoch erst nach Beendigung der Leseoperation weiter.

REQNO = zahl

Nur für Plattendateien:
gibt die Nummer der Ein-/Ausgabe-Anforderung an, die dieser Operation zugeordnet ist. Wird dieser Operand angegeben, darf der Operand FECB nicht angegeben werden.

Voreinstellung:

REQNO=1

SETL

Bewirkt, dass der Dateizeiger auf die angegebene PAM-Seite eingestellt wird.

SETLPP

Nur für Plattendateien:
bewirkt, dass der Last Page Pointer (Dateiende-Zeiger) auf die angegebene PAM-Seite gesetzt wird; sie muss bereits zu der Datei gehören. Diese Operation ist nicht zulässig für Eingabedateien (OPEN INPUT) und Dateien, die mit SHARUPD=WEAK oder YES eröffnet wurden.
Node-Files werden nach SETLPP abgeschnitten („truncate“).

SYNC

wartet auf Ein-/Ausgabe-Beendigung und leert den Steuerungspuffer bei Magnetbandkassetten; für Dateien, die nicht auf Magnetbandkassetten stehen, entspricht SYNC dem WAIT. Der Operandenwert kann nur für die 31-Bit-Schnittstelle des Makros angegeben werden.

UNLOCK

Nur für Plattendateien:
gibt gesperrte PAM-Blöcke frei (siehe auch Operanden HP und LEN).

WRT

Stößt das Schreiben eines Datenblocks aus dem Hauptspeicher in die Datei an; unmittelbare Fortsetzung des Auftrags.

WRTWT

wie WRT; Fortsetzung des Auftrags jedoch erst nach Beendigung der Schreiboperation.

WRTWU

wie WRTWT; unmittelbar nach dem Abschluss der Ein-/Ausgabe-Operation wird die soeben geschriebene PAM-Seite freigegeben.

WT

Bewirkt, dass das Programm auf den Abschluss einer bestimmten Ein-/Ausgabe-Anforderung wartet. Nach erfolgtem Abschluss läuft das Programm weiter.

Hinweise zur Programmierung

1. Der PAM-Makroaufruf zerstört die Register 0, 1, 14 und 15.

2. Die erste PAM-Seite einer PAM-Datei hat die Nummer 1. Bei der Eröffnung einer PAM-Datei erhält der Dateizeiger jedoch den Anfangswert 0. Der HP-Operand bleibt bei den Operationen WT bzw. CHK und SYNC unbeachtet. WT bzw. CHK beziehen sich nicht auf PAM-Seiten, sondern auf Ein-/Ausgabe-Anforderungen.

3. Jede Operation (ausgenommen WT, CHK, SYNC sowie SETLPP auf Banddatei), bei der keine Fehlerroutine angesprungen wird, bewirkt, dass der Dateizeiger die Nummer der PAM-Seite erhält, auf die soeben zugegriffen wird. Dies gilt auch für Sperrungen und Freigaben, auch bei SHARUPD=NO. Der Dateizeiger bleibt grundsätzlich unverändert, wenn Operationen nicht normal abgeschlossen werden, sondern zu einer Fehlerroutine führen.

   Bei PAM- und SAM-Dateien ohne PAM-Schlüssel (Eigenschaft BLKCTRL=DATA oder BLKCTRL=NO) enthält der Dateizeiger anschließend die Nummer des letzten 2-KB-Blockes in dem Logischen Datenblock, auf den zuletzt zugegriffen wurde.
   (Bei der Berechnung des Dateizeigers wird also die Länge auf das nächstgrößere Vielfache von BLKSIZE aufgerundet.)

4. Bezeichnet für eine Plattendatei n die Anzahl derjenigen PAM-Seiten, die einer Datei bereits zugewiesen sind, und k den Wert der Sekundärzuweisung, so sind folgende Regeln zu beachten:

   PAM-Operation	Bedeutung
   RD RDEQU RDWT LRD LRDWT	HP = zahl, 1 <= zahl <= n
   WRT WRTWT WRTWU	HP = zahl, 1 <= zahl <= n + k sobald eine PAM-Seite mit LHP > n geschrieben wird, erfolgt eine Sekundärzuweisung; der Umfang der Datei wächst auf n + k PAM-Seiten sollen mehrere aufeinander folgende PAM-Seiten mit einem PAM-Makroaufruf geschrieben werden (gekettete Ein-/Ausgabe), muss (spätestens) nach der ersten Sekundärzuweisung Speicherplatz für alle zu schreibenden Blöcke zugewiesen sein, d.h. für den letzten zu schreibenden Block gilt: LHP <= n+k
   LOCK UNLOCK	HP = zahl, zahl > 0 es können später PAM-Seiten gesperrt oder freigegeben werden, die momentan nicht zugewiesen sind; eine Sperre/ Freigabe ist nicht mit einer Sekundärzuweisung verbunden

5. Der mit REQNO genannte Wert muss kleiner oder gleich dem im PAMREQS-Operanden des FCB genannten Wert sein.

6. Der Operand REQNO bleibt unberücksichtigt bei den Operationen LOCK, UNLOCK und SETL. Bei den Operationen WT, CHK und SYNC wird damit angegeben, für welche Ein-/Ausgabe-Anforderung die Operation ausgeführt werden soll.

7. Jeder einzelnen Anforderungsnummer (REQNO) kann nur eine asynchrone Ein-/Ausgabe-Operation zugeordnet werden. Die Beendigung dieser asynchronen Ein-/Ausgabe-Operation kann entweder explizit durch Angabe ihrer Anforderungsnummer in einer WT-Operation oder implizit durch eine neue Lese- oder Schreiboperation an die gleiche Anforderungsnummer abgewartet werden. Wird beim impliziten Warten auf die Beendigung einer Ein-/Ausgabe-Anforderung ein Fehler entdeckt, so lautet der Fehlercode '997', und die Anforderung, die den impliziten WT verursachte, wird nicht ausgeführt.

8. Anforderungsnummern (REQNO) sind Betriebsmittel des Systems; ein Missbrauch kann die Leistungsfähigkeit des Systems mindern.

9. Will der Benutzer für Ein- / Ausgabeoperationen den vom OPEN angelegten Datenpuffer verwenden (Operand LOC=1 oder LOC=2), so darf der Wert des Operanden LEN nicht größer sein als BLKSIZE, da sonst der Puffer nicht zur Aufnahme der Daten ausreichen würde.

10. Bei Banddateien muss der Wert für LEN genau die Länge eines Bandpuffers angeben. Bei Dateien mit BLKCTRL=PAMKEY ist dies ein PAM-Block (2048 Byte); dies entspricht der Angabe LEN=STD bzw. LEN=(STD,1) oder LEN=2048 (16 Byte für den PAM-Schlüssel werden vom System hinzugefügt).

11. Bei Banddateien ohne PAM-Schlüssel (Eigenschaft BLKCTRL=DATA oder BLKCTRL= NO) wird ein Nichtstandardblock in der mit LEN vereinbarten Länge geschrieben; beim Lesen wird versucht, einen Block in der mit LEN vereinbarten Länge zu lesen. Bei PAM-oder SAM-Dateien ohne PAM-Schlüssel darf der Wert für LEN nicht größer sein als BLKSIZE, bei ISAM-Dateien ohne PAM-Schlüssel nicht größer als 2048 bzw. (STD,1).

12. Ist beim Lesen von Banddateien ohne PAM-Schlüssel der Wert für LEN kleiner als die Blocklänge der Datei, so wird die Leseoperation mit Fehler beendet. Um solche Fehler zu vermeiden, sollte man eine Banddatei ohne PAM-Schlüssel stets mit LEN=BLKSIZE lesen, also mit dem größten zulässigen Wert für LEN. Bei Dateien mit BLKCTRL=DATA kann dann die Länge der gültigen Daten aus dem Blockkontrollfeld ermittelt werden.

13. Bei einer Schreiboperation (WRT, WRTWT, WRTWU) auf eine Datei mit BLKCTRL= DATA behandelt UPAM die ersten 12 Byte als Blockkontrollfeld und überschreibt sie mit Blockkontrollinformation.

14. Bei Dateien mit BLKCTRL=DATA und Operationen, die eine Ein-/Ausgabe anfordern, muss der Wert für LEN so gewählt werden, dass das Blockkontrollfeld stets vollständig im Datenpuffer liegt. Dies ist der Fall, wenn folgende Bedingungen erfüllt sind:

    • Bei PAM- und SAM-Plattendateien:
      LEN = n*BLKSIZE oder LEN > n*BLKLSIZE + 12 (n: Anzahl der Datenblöcke)

    • Bei ISAM-Plattendateien:
      LEN = n*2048 oder LEN > n*2048 + 12 (n: Anzahl der Datenblöcke)

    • Bei Banddateien: LEN > 12

15. Für Dateien mit BLKCTRL=DATA gilt folgende Parallelitätseinschränkung:
    Bei der Verarbeitung einer PAM-Datei mit BLKCTRL=DATA dürfen die IOAREAs nicht parallel für mehrere I/O-Aufträge verwendet werden, weil dabei der Inhalt des Blockkontrollfeldes undefiniert wäre. Beispiel:

    • Unzulässig ist:

    PAM   WRT,FCB1,LOC=BUFFER
    PAM   WRT,FCB2,LOC=BUFFER       (Parallele I/Os auf BUFFER)
    PAM   WT,FCB1
    PAM   WT,FCB2

    • Zulässig ist:

    PAM   WRTWT,FCB1,LOC=BUFFER     (Nacheinander ausgeführte
    PAM   WRTWT,FCB2,LOC=BUFFER     I/Os auf BUFFER)

16. Bei LOCK- oder UNLOCK-Operationen wird LEN=0 behandelt wie LEN=2048 (oder LEN=n mit 1 <= n <= 2048). Bei jedem anderen Wert für LEN werden so viele PAM-Blöcke gesperrt, wie bei bei einer Ein-/Ausgabeoperation mit dieser LEN-Angabe gelesen oder geschrieben würden.
    Bei PAM- und SAM-Dateien ohne PAM-Schlüssel (Eigenschaft BLKCTRL=DATA oder BLKCTRL=NO) wird intern jeweils nur der erste 2-KB-Abschnitt jedes betroffenen logischen Datenblockes gesperrt, was jedoch die Sperrung des gesamten Datenblockes bewirkt.

17. Bei Dateien mit PAM-Schlüssel (BLKCTRL=PAMKEY) ist zu beachten:

    • Wird ein WT für eine erfolgreiche Leseoperation gegeben (explizit oder implizit), so wird der 16 Byte lange PAM-Schlüssel, der dem gelesenen Block zugeordnet ist, in das mit KEYFLD bezeichnete Feld gebracht. Dabei bewirkt eine CHK-Operation, die nach einer abgeschlossenen Ein-/Ausgabe-Operation gegeben wird, das Gleiche wie eine WT-Operation.

    • Bringt ein Anwender bei einer Schreiboperation irgendeine Information in die letzten 8 Byte des von diesem Operanden angegebenen 16-Byte-Feldes, so wird diese Information in die Datei geschrieben als Teil des PAM-Schlüssels, der der zu schreibenden PAM-Seite zugeordnet ist (nicht empfohlen). UPAM erstellt grundsätzlich die ersten 8 Byte dieses Feldes vor Beginn des Schreibvorgangs.

    • Der Operand KEYFLD bleibt unberücksichtigt bei den Operationen WT, CHK, UNLOCK, SETL und SETLPP.