ADD-ELEMENT nimmt Dateien als Voll- bzw. Delta-Elemente in eine Bibliothek auf. Die Elementdaten werden standardmäßig von SYSDTA gelesen. Sie können aber auch von einer explizit angegebenen Datei oder *OMF gelesen werden. Erfolgt die Anweisung jedoch aus der EDT-Anweisungszeile, werden die Elementdaten standardmäßig aus der aktuellen EDT-Arbeitsdatei gelesen.
Die Dateien werden immer ohne Präfix, d.h. ohne CATID und USERID, als Element in eine Bibliothek aufgenommen, es sei denn, der Benutzer hat in der Konstruktionsangabe explizit ein Präfix angegeben.
Dateien, die mit RECORD-FORMAT=*UNDEFINED katalogisiert sind, können ebenfalls in Bibliotheken aufgenommen werden. Dateien, die RECORD-FORMAT=*FIXED haben, können nur über SOURCE-ATTRIBUTES=*KEEP abgespeichert werden.
Die Satzformate FIXED und UNDEFINED werden in das Satzformat VARIABLE umgewandelt; d.h. mit einem 4 Byte Satzkopf versehen. Die Satzlänge inklusive Satzkopf darf 32KByte nicht überschreiten.
Dateigenerationsgruppen können nur über Linknamen und eine LMS-gültige Elementbezeichnung aufgenommen werden.
LMS übernimmt bei der ADD-ELEMENT-Anweisung das Katalogattribut CCS der Datei als Elementattribut. Werden die Daten von SYSDTA gelesen, erhält das erzeugte Element als Attribut den für SYSDTA eingestellten CCS-Namen. Beim Lesen von *OMF wird den Elementen „kein Code“ zugeordnet. Werden die Daten aus einer EDT-Arbeitsdatei gelesen, erhält das erzeugte Element als Attribut den aktuell eingestellten CCS-Namen des EDT.
Werden mit der ADD-ELEMENT Anweisung Dateien vom Typ L eingelesen, die keine gültigen Dateien vom Typ PAM LLM sind, dann werden folgende Meldungen von LMS ausgegeben:
BND5201 UNGUELTIGES FORMAT DER DATEI ‘xxx' . ANWEISUNG ABGEBROCHEN
BND1102 BINDER ABNORMAL BEENDET. FEHLERKLASSE: 'RECOVERABLE ERROR'
ADD-ELEMENT | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
FROM-FILE = *STD / *SYSDTA(...) / *ALL / <filename 1..80 without-vers with-wild>/*LINK(..) / *OMF
Angabe derjenigen Datei, die als Element in die Bibliothek aufgenommen werden soll.
FROM-FILE = *STD
Standardmäßig werden die Datensätze von der Systemdatei SYSDTA gelesen. Erfolgt die Anweisung jedoch aus der EDT-Anweisungszeile, werden die Datensätze standardmäßig aus der aktuellen EDT-Arbeitsdatei gelesen.
Zulässige Elementtypen:
für Voll-Elemente: S, M, P, J, D, X oder davon abgeleitete Typen
für Delta-Elemente: analog
FROM-FILE = *SYSDTA(...)
Die Datensätze werden mit RDATA von der Systemdatei SYSDTA gelesen. Die Datensätze müssen direkt auf die ADD-ELEMENT-Anweisung folgen.
Zulässige Elementtypen:
für Voll-Elemente: S, M, P, J, D, X, R oder davon abgeleitete Typen
für Delta-Elemente: S, M, P, J, D, X oder davon abgeleitete Typen
END = '*END' / <c-string 1..8>
Endekriterium für die Eingabe. Die Folge der Datensätze muss mit ’*END’ oder einem selbst definierten Endekriterium (siehe Beispiel) abgeschlossen werden. Fehlt das Endekriterium in den Eingabedaten, wird bis EOF gelesen.Hinweis
Werden Datensätze von der Systemdatei SYSDTA=(SYSCMD) gelesen, so dürfen sie nicht mit dem Zeichen „/“ beginnen. Der Grund dafür ist, dass der RDATA-Makro solche Sätze als Kommandos interpretiert und daher den Return-Code für EOF übergibt. Es ist damit nicht möglich, System-Kommandos als Datensätze zu übergeben.
FROM-FILE = *ALL
Es wird versucht, alle Dateien der Kennung in die Bibliothek zu übernehmen. Tritt bei einer Datei ein Fehler auf, wird diese übergangen und mit der nächsten Datei fortgefahren.
FROM-FILE = <filename 1..80 without-vers with-wild>
Die Daten werden aus der angegebenen Datei gelesen.
Zulässige Elementtypen:
für Voll-Elemente: S, M, P, J, D, X, R, L, C oder davon abgeleitete Typen
für Delta-Elemente: S, M, P, J, D, X oder davon abgeleitete Typen
Dateien vom Typ PAM können nur als Voll-Elemente unter dem Elementtyp X oder L oder davon abgeleiteten Elementtypen abgelegt werden.
FROM-FILE = *LINK(...)
Die Daten werden aus der über den Dateikettungsnamen angegebenen Datei gelesen.
LINK-NAME = <structured-name 1..8>
Dateikettungsname, der auf die Datei verweist.
FROM-FILE = *OMF
Gilt nur für Typ R Elemente.
Die Daten werden aus der OMF-Datei gelesen. Es werden alle Module aus der OMF-Datei übernommen. Sind im EAM-Bereich mehrere gleichnamige Module enthalten, übernimmt LMS den zuletzt übersetzten Modul in die Bibliothek.
TO-ELEMENT = *LIBRARY-ELEMENT(...)
Angabe, wohin und unter welchem Namen das Element aufgenommen werden soll.
LIBRARY = *STD / *LINK(...) / <filename 1..54 without-vers>
Angabe der Bibliothek, in die das Element aufgenommen werden soll.
LIBRARY = *STD
Die durch OPEN-LIBRARY global eröffnete Bibliothek.
LIBRARY = *LINK(...)
Die über einen Dateikettungsnamen zugewiesene Bibliothek.
LINK-NAME = <structured-name 1..8>
Dateikettungsname der Bibliothek, der vor dem Aufruf von LMS mit einem /ADD-FILE-LINK-Kommando vereinbart wurde.
LIBRARY = <filename 1..54 without-vers>
Name der Bibliothek, in die die Datei als Element aufgenommen werden soll.
ELEMENT = *BY-SOURCE(...) /
<composed-name 1..132 with-under with-wildcard-constr>(...)
Name, den das neu aufzunehmende Element erhalten soll. Eine Konstruktionsangabe bezieht sich auf den Dateinamen.
ELEMENT = *BY-SOURCE(...)
Der Elementname entspricht dem Dateinamen bzw. dem Modulnamen bei *OMF.
VERSION = *LMS-DEFAULT / *HIGHEST-EXISTING / *INCREMENT / *UPPER-LIMIT / <composed-name 1..24 with-under>
Version, die das neu aufzunehmende Element erhalten soll.
VERSION = *HIGHEST-EXISTING
Abhängig von der unter dem Typ geltenden Konvention wird unter existierenden Elementen gleichen Typs und Namens die höchste zu BASE passende Version überschrieben, ansonsten wird eine Defaultversion erzeugt.
VERSION = *INCREMENT
Abhängig von der unter dem Typ geltenden Konvention wird unter existierenden Elementen gleichen Typs und Namens eine neue, höhere Version erzeugt, ansonsten eine Defaultversion (siehe auch "Konvention: STD-TREE").
VERSION = *UPPER-LIMIT
Die höchstmögliche Version X’FF’ wird erzeugt.
VERSION = <composed-name 1..24 with-under>
Der hier angegebene Text wird als Versionsbezeichnung interpretiert.
BASE = *STD / <composed-name 1..24 with-under with-wild>
Legt die Basis für das Zielelement fest. Wird der Operand BASE in der Form <composed-name 1..23>* eingegeben, wird er als Präfix interpretiert.
Näheres zu den Wirkungen von BASE siehe "Versionsbezeichnungen".
ELEMENT = <composed-name 1..132 with-under with-wild-constr>(...)
Das Element wird mit dem hier angegebenen Namen abgelegt.
VERSION = *LMS-DEFAULT / *HIGHEST-EXISTING / *INCREMENT / *UPPER-LIMIT / <composed-name 1..24 with-under>
Version, die das neu aufzunehmende Element erhalten soll.
Beschreibung der Operanden siehe oben.
BASE = *STD / <composed-name 1..24 with-under with-wild>
Legt die Basis für das Zielelement fest. Näheres zur Angabe der Basis siehe "Versionsbezeichnungen".
TYPE = *LMS-DEFAULT / <alphanum-name 1..8>
Typ, den das neu aufzunehmende Element erhalten soll.
USER-DATE = *TODAY / *BY-SOURCE / <date 8..10 with-compl>
Datum, das vom Benutzer vergeben wird.
USER-DATE = *TODAY
Das aktuelle Tagesdatum wird vergeben.
USER-DATE = *BY-SOURCE
Das CHANGE-DATE der Datei wird vergeben.
USER-DATE = <date 8..10 with-compl>
Das Datum muss in der Form [JJ]JJ-MM-TT eingegeben werden.
STORAGE-FORM = *LMS-DEFAULT / *STD / *FULL / *DELTA
Speicherform für das neu anzulegende Element. Die Speicherform darf den Einstellungen durch MODIFY-TYPE-ATTRIBUTES bzw. MODIFY-LIBRARY-ATTRIBUTES nicht widersprechen, und alle Elemente eines Typs und Namens müssen die gleiche Speicherform haben.
STORAGE-FORM = *STD
Das Element wird gemäß der für den Elementscope geforderten Speicherform angelegt. Widersprüchliche Anforderungen führen auf Fehler. Ist nichts besonderes gefordert, wird Vollspeicherung gewählt.
STORAGE-FORM = *FULL
Das Element wird vollgespeichert angelegt (Fehler, falls nicht zulässig).
STORAGE-FORM = *DELTA
Das Element wird delta-gespeichert angelegt (Fehler, falls nicht zulässig). Die Angabe ist zulässig für die Elementtypen: S, P, D, J, M, X bzw. davon abgeleitete Elementtypen.
ELEMENT-ATTRIBUTES = *LMS-DEFAULT / *PARAMETERS(...)
Bestimmt, ob die Dateieigenschaften und auch der ISAM-Schlüssel in das Ausgabeelement mit übernommen werden.
ELEMENT-ATTRIBUTES = *PARAMETERS(...)
SOURCE-ATTRIBUTES = *LMS-DEFAULT / *STD / *IGNORE / *KEEP
Speichern von Dateiattributen. Dieser Operand ist wirkungslos, wenn die Daten von SYSDTA, *OMF oder aus einer EDT-Arbeitsdatei gelesen werden. Es werden keine Ursprungsattribute gespeichert.
Werden die Daten aus einer Datei vom Filetyp UPAM gelesen, so ist die Angabe wirkungslos; es wird immer wie im Fall *KEEP verfahren.
SOURCE-ATTRIBUTES = *STD
Es werden keine Dateiattribute gespeichert. Im Fall von ISAM-Dateien ist es nur möglich, ISAM-Dateien mit KEY-POSITION = 5, KEY-LENGTH <= 16 und RECORD-FORMAT = VARIABLE in das Element aufzunehmen. Es erfolgt eine Warnung, dass die ISAM-Schlüssel nicht mit aufgenommen wurden.
SOURCE-ATTRIBUTES = *IGNORE
Wie bei SOURCE-ATTRIBUTES = *STD, jedoch ohne Warnung.
SOURCE-ATTRIBUTES = *KEEP(...)
Folgende Dateiattribute werden unverändert im neu aufzunehmenden Element gespeichert: ACCESS-METHOD, RECORD-FORMAT, RECORD-SIZE, BUFFER-LENGTH, PERFORMANCE, USAGE, ACCESS und USER-ACCESS. Ist ACCESS-METHOD= ISAM, so werden PADDING-FACTOR, LOGICAL-FLAG-LENGTH, VALUE-FLAG-LENGTH, PROPAGATE-VALUE-FLAG und auch die ISAM-Schlüssel sowie Informationen über ISAM-Sekundärschlüssel zusätzlich gespeichert.
LMS speichert den Last Byte Pointer (LBP) zusätzlich
- für PAM-Elemente vom Typ X
- für Elemente vom Typ C, wenn KEEP-TYPES = *ALL angegeben wurde
KEEP-TYPES = *LMS-DEFAULT / *STD / *ALL
bestimmt die Elementtypen, für die Dateiattribute gespeichert werden sollen.
KEEP-TYPES = *STD
Attribute werden für Elemente der Basistypen S,M,P,D,J,X gespeichert.
KEEP-TYPES = *ALL
Attribute werden für Elemente aller Basistypen gespeichert, die für ADD-ELEMENT zulässig sind.
DELETE-SOURCE = *LMS-DEFAULT / *NO / *YES
Hier kann der Benutzer bestimmen, ob die ursprüngliche Datei erhalten bleiben oder gelöscht werden soll. Dieser Operand ist wirkungslos, wenn die Daten von SYSDTA, *OMF oder aus einer EDT-Arbeitsdatei gelesen werden.
DELETE-SOURCE=*NO
Die ursprüngliche Datei wird nicht gelöscht.
DELETE-SOURCE=*YES
Die ursprüngliche Datei wird gelöscht.
PROTECTION= *LMS-DEFAULT / *STD / *BY-SOURCE
Elementschutz für das aufzunehmende Element. Dieser Operand ist wirkungslos, wenn die Daten von SYSDTA, *OMF oder aus einer EDT-Arbeitsdatei gelesen werden.
PROTECTION=*STD
Existiert das Element bereits, bleibt der Elementschutz unverändert. Existiert das Element noch nicht und ist für die Bibliothek bzw. den Typ des Elements ein initialer Elementschutz festgelegt, so erhält das Element diesen Schutz.
PROTECTION=*BY-SOURCE
Das Element erhält einen Elementschutz entsprechend den Dateischutzattributen des aktivierten Zugriffsschutzmechanismus der Datei. ADD-ELEMENT wird mit einer Fehlermeldung abgewiesen, wenn die Datei durch den Zugriffsschutzmechanismus Access Control List (ACL) geschützt ist.
WRITE-MODE = *LMS-DEFAULT / *CREATE / *REPLACE / *EXTEND / *ANY
Überschreiben eines Elementes gleichen Namens. Existiert das Element nicht unter diesem Namen, wird es neu angelegt.
Ist das zu speichernde Element ein Delta-Element, ist darauf zu achten, dass das Element ein Blatt des Delta-Baumes sein muss. Nur Blätter eines Delta-Baumes dürfen überschrieben werden.
WRITE-MODE = *CREATE
Das Zielelement darf noch nicht existieren und wird neu erzeugt.
WRITE-MODE = *REPLACE
Ein Element wird nur dann überschrieben, wenn schon ein Element gleichen Namens vorhanden ist. Ansonsten wird ADD-ELEMENT mit einer Fehlermeldung abgewiesen.
WRITE-MODE = *EXTEND
Ein Element wird jedoch nur dann erweitert, wenn im Element keine ISAM-Schlüssel gespeichert sind und die im Element gespeicherten Dateimerkmale mit den Merkmalen der Datei bis auf den Dateinamen übereinstimmen. Sonst wird ADD-ELEMENT mit einer Fehlermeldung zurückgewiesen.
EXTEND ist nicht für Delta-Elemente und bei Eingabe von SYSDTA erlaubt.
WRITE-MODE = *ANY
Das Zielelement wird ersetzt, wenn es bereits existiert. Ansonsten wird es neu angelegt.
DIALOG-CONTROL =*LMS-DEFAULT / *NO / *YES / *ERROR
Dieser Operand legt fest, ob während der Ausführung einer Anweisung ein Dialog mit dem Benutzer geführt werden soll oder nicht.
Nähere Erläuterungen zur Dialogführung unter MODIFY-LMS-DEFAULTS.
Anweisungs-Returncode
(SC2) | SC1 | Maincode | Bedeutung |
0 | CMD0001 | Ohne Fehler | |
2 | 0 | LMS0064 | GCCSN Makro Fehler; kein CCS-Name spezifiziert |
2 | 0 | LMS0071 | XHCS nicht geladen |
2 | 0 | LMS0095 | Eingabesätze fehlen |
2 | 0 | LMS0102 | Unvollständiger Modul in EAM Datei |
2 | 0 | LMS0129 | Anweisung abgebrochen durch Benutzer |
1 | CMD0230 | Syntaxfehler | |
32 | LMS1002 | Interner Fehler | |
64 | LMS0020 | Ziel-Element oder Ziel-Datei nicht vorhanden | |
64 | LMS0213 | Name existiert als Delta-Element | |
64 | LMS0214 | Name existiert als Voll-Element | |
64 | LMS0301 | Datei nicht gefunden | |
64 | LMS0509 | Ziel-Element oder Ziel-Datei schon vorhanden | |
64 | LMS0510 | Basis nicht gefunden | |
64 | LMS1003 | Fehler während Mengenverarbeitung (Wildcard) bei mindestens einem Element oder einer Datei | |
64 | LMS1004 | Sonstige Fehler | |
64 | PLA0223 | Nur Blätter eines Delta-Baumes überschreibbar | |
64 | PLA0224 | Speicherform nicht erlaubt | |
64 | PLA0229 | Kein Zugriffsrecht für das Element | |
64 | PLA0233 | Ausleihstatus verhindert Elementzugriff | |
64 | PLA0475 | Funktion verletzt Versionsautomatismus | |
64 | PLA0476 | Version passt nicht zur geltenden Konvention | |
64 | PLA0478 | Versionsüberlauf bei Erhöhung | |
130 | LMS0041 | Systemadressraum erschöpft | |
130 | LMS0411 | Bibliothek gesperrt | |
130 | LMS0412 | Element gesperrt | |
130 | LMS0413 | Typ gesperrt |
Notwendige Zugriffsrechte
Bei FROM-FILE: Leserecht für die Datei
Sind von der Anweisung mehrere Dateien betroffen, so werden Dateien ohne Leserecht von der Anweisung ausgenommen.
Bei TO-ELEMENT: Lese- und Schreibrecht für LIBRARY Administrationsrecht, sofern die angegebene Elementbezeichnung neu ist. Ansonsten nur Schreibrecht für das unter der angegebenen Elementbezeichnung existierende Element (kein Administrationsrecht mehr erforderlich).
Bei STORAGE-FORM=*DELTA muss für das durch BASE bestimmte Element Leserecht gegeben sein.
Bei aktivem WRITE-CONTROL muss die USERID des Benutzers bei dem durch BASE bestimmten Element als HOLDER eingetragen sein, sofern eine Basisversion existiert. Eine neue Version kann nur erzeugt oder diese Basisversion überschrieben werden, wenn Schreibrecht gegeben ist. Administrationsrecht ist in diesem Falle nicht mehr erforderlich.
Hinweise
Bei Aufnahme einer Datei in eine Bibliothek gilt nicht das Erzeugungsdatum der Datei, sondern das Erzeugungsdatum des Elementes.
Wird SOURCE-ATTRIBUTES=*KEEP angegeben, ist zu beachten:
Durch eventuell vorhandene ISAM-Schlüssel kann die nachfolgende Verarbeitung wie Übersetzen und /CALL-PROCEDURE behindert werden. Dieser Parameterwert eignet sich vor allem zur Archivierung.Beim Anlegen eines Elements ist die unter dem Typ geltende Konvention zu beachten.
Bei Aufnahme von temporären Dateien mit Wildcards ist keine Konstruktionsangabe des Zielelementnamens erlaubt, d.h. ELEM = darf nur *BY-SOURCE sein.
Bei Aufnahme von temporären Dateien mit ELEM = *BY-SOURCE erhält das Element den internen Dateinamen. Dieses Element kann unter einer anderen TASK ohne explizite Angabe eines Dateinamens nicht wieder in eine Datei ausgegeben werden.
Bei aktivem WRITE-CONTROL in der Ausgabebibliothek wird dem zu schreibenden Element von der Zugriffsmethode ein Kommentarsatz (Satzart 2) zugefügt, der HOLDER, DATE und TIME des Vorgangs protokolliert. Der Satz wird als erster Satz der Satzart geschrieben. Wird das Element überdies zur Basis einer anderen Version geschrieben (also nicht erste Version unter einem Namen), werden die Elementattribute STATE, HOLDER und alle Rechte von der Basisversion auf die neue Version übernommen. Die CCSN wird von der Quelldatei übernommen. Das USER-DATE wird neu bestimmt.
Wird PROTECTION=*BY-SOURCE angegeben, ist zu beachten:
Die Aufnahme der Datenschutzattribute des aktivierten Zugriffsschutzmechanismus in einen entsprechenden Elementschutz ist für die Mechanismen Standard-Zugriffskontrolle, BACL und GUARDS möglich. Hierbei erhält das Element für die Zugriffsrechte (read, write, execute) beim aktivierten Zugriffsschutzmechanismus der Datei folgenden entsprechenden Schutzmechanismus:Schutzmechanismus der Datei
Schutzmechanismus des Elementes
Standard-Zugriffskontrolle
(ACCESS / USER-ACCESS)
Schutz durch BACL
(ohne Kennwort)BACL
Schutz durch BACL
(ohne Kennwort)GUARDS 1
Schutz durch GUARD
1Sonderfall:
Ist eines der Zugriffsrechte der Datei beim Schutzmechanismus GUARDS mit dem Wert NONE (kein Zugriff für dieses Recht möglich) belegt, erhält das Element für das entsprechende Recht Schutz durch BACL mit USER=NONE (kein Zugriff möglich).Bestehende Kennwörter auf Dateien gehen nicht in den Elementschutz ein.Bei der Aufnahme von Dateien auf bestehende Elemente gehen die ggf. bestehenden Elementschutzeinstellungen der Zugriffsrechte (read, write, execute) verloren.
Für das Ausleihrecht (hold) gilt die Verfahrensweise wie bei PROTECTION=*STD. Das heißt, existiert das Element bereits, bleibt der Elementschutz in Bezug auf das Ausleihrecht unverändert. Existiert das Element noch nicht und ist für die Bibliothek bzw. den Typ des Elementes ein initialer Elementschutz in Bezug auf das Ausleihrecht festgelegt, erhält das Element diese Einstellung.
Beispiele
Aufnehmen eines Elementes
Das Element testelem wird in die Bibliothek lib1 unter dem gleichen Namen aufgenommen. Die Typangabe muss hier explizit in der ADD-ELEMENT-Anweisung angegeben werden, da standardmäßig der Typ mit *NONE voreingestellt ist.
/show-file-attributes TESTELEM . //start-lms //open-library lib1,*update //add-element from-file=testelem,to-elem=*lib(type=d) . .
Lesen von SYSDTA und der Definition des Endekriteriums
/start-lms -------------------------------------------------------------------- (1) //open-library lib1,*update -------------------------------------------------- (2) //modify-lms-defaults (type=d) ----------------------------------------------- (3) //add-element *sysdta(end=c'stop'),to-element=*lib(element=letter.a) --------- (4) * sehr geehrte ... ----------------------------------------------------------- (5) . . . *STOP ------------------------------------------------------------------------ (6) //end ------------------------------------------------------------------------ (7)
(1)
LMS wird gestartet.
(2)
Die Bibliothek mit dem Namen lib1 wird zum Lesen und Schreiben geöffnet.
(3)
Der LMS-Defaultwert, der für die Typ-Angabe *NONE ist, wird in die Element-typ-Angabe „D“ geändert. Diese Einstellung gilt für den gesamten LMS-Lauf, wenn nicht eine neue MODIFY-LMS-DEFAULTS-Anweisung betreffend des Elementtyps gegeben wird oder der Typ lokal in einer Anweisung geändert wird.
(4)
Es sollen Datensätze von SYSDTA eingelesen werden, wobei als Endekriterium das Wort stop vereinbart wird. Die Datensätze sollen unter dem Elementnamen letter.a in die durch OPEN-LIBRARY eröffnete Bibliothek lib1 abgelegt werden. Der Elementtyp muss nicht mehr angegeben werden.
(5)
Eingabe des Textes. Der Text ’Sehr geehrte ...’ wird so gespeichert, wie er eingetippt wurde.
(6)
Die Aufnahme der Datensätze wird durch die Angabe von stop beendet.
(7)
LMS wird beendet.