Makrotyp: S-Typ (E-Form/L-Form/D-Form/C-Form) (siehe "Typen von Makroaufrufen")
Der Makro CREAIX definiert einen oder mehrere Sekundärschlüssel (maximal 30) für eine NK-ISAM-Datei. Insgesamt können für eine Datei bis zu 30 Sekundärschlüssel vereinbart werden; sie sind jeweils durch ihren im CREAIX-Aufruf festgelegten Namen zu identifizieren. Über seinen Namen kann jeder dieser Sekundärschlüssel in den Makros GET, GETR, GETKY sowie SETL angesprochen werden und ermöglicht es so dem Anwender, auf Datensätze anhand von Sekundärschlüsselwerten zuzugreifen.
Zur Einrichtung von Sekundärschlüsseln werden zunächst alle Sätze der Datei sequenziell gelesen. Zu jedem Satz wird ein Tripel – bestehend aus dem Index in der Liste der zu erstellenden Sekundärschlüssel, dem jeweiligen Sekundärschlüssel selbst und dem jeweiligen Primärschlüssel – gebildet. Diese Einheiten werden anschließend pro Sekundärschlüssel nach den Sekundärschlüsselwerten sortiert und, mit Zeitstempeln versehen, als Einträge in die Sekundärindexblöcke übernommen, die für diesen Sekundärschlüssel angelegt werden.
Sekundärschlüssel können nur für existierende NK-ISAM-Dateien eingerichtet werden, d.h. für Dateien, die schon einmal im Modus OUTPUT oder oder OUTIN eröffnet waren. Darüber hinaus dürfen in einer NK-ISAM-Datei, für die Sekundärschlüssel vereinbart werden sollen, Primärschlüsselwerte nicht mehrfach vorkommen (keine DUPEKYs!), und es dürfen weder Logische noch Wertmarkierungen definiert sein. Zum Zeitpunkt des Makroaufrufs darf für die NK-ISAM-Datei nicht (durch ein ADD-FILE-LINK-Kommando) SHARED-UPDATE=*YES bzw. (durch ein Makro) SHARUPD=YES eingestellt sein, und während der Erstellung des Sekundärschlüssels können keine anderen Benutzer auf sie zugreifen.
Wird während der Erstellung des Sekundärschlüssels das Programm abgebrochen, so wird der Sekundärschlüssel im Kontrollblock dieser Datei als unvollständig markiert. Beim Versuch, eine solche Datei zu öffnen wird – falls im Programm vorgesehen – der OPENER-Ausgang genommen und im FCB der Fehlerschlüssel 0D84 abgelegt. Erst nach dem Löschen des unvollständigen Sekundärschlüssels (und ggf. seiner erneuten Vereinbarung mit CREAIX) kann die Datei wieder geöffnet werden.
Aus Performancegründen empfiehlt es sich, Sekundärschlüssel für eine Datei erst zu definieren, wenn sie bereits mit Datensätzen geladen ist.
Format
Operation | Operanden |
|
|
| |
| |
|
Operandenbeschreibung
DUPKEY
legt für jeden anzulegenden Sekundärschlüssel (Operand KEYNAME) fest, ob gleiche Werte in verschiedenen Datensätzen vorkommen dürfen.
Die runden Klammern in dieser Angabe können weggelassen werden, wenn die Liste nur eine Spezifikation für DUPKEY enthält. Die Angabe einer Liste ist nur für VERSION=2 zulässig, für VERSION=1 ist nur eine Angabe ohne Klammern erlaubt.
= YES
ist Voreinstellung: Gleiche Werte des Sekundärschlüssels dürfen in der Datei mehrfach auftreten.
= NO
In der Datei dürfen verschiedene Datensätze nicht ein und denselben Wert für den Sekundärschlüssel enthalten.
FILE = pfadname
Bezeichnet die NK-ISAM-Datei, für die der Sekundärschlüssel vereinbart werden soll, mit:
<c-string 1..54: filename 1..54>
Die Datei muss zum Zeitpunkt des CREAIX-Aufrufs mindestens einmal im Modus OUTPUT oder OUTIN eröffnet worden sein und darf keine mehrfach auftretenden Primärschlüsselwerte, keine logischen Markierungen und keine Wertmarkierungen enthalten. Die Angabe im FILE-Operanden wird ignoriert, wenn zugleich der LINK-Operand angegeben ist.
Pfadname bedeutet [:catid:][$userid.]dateiname
catid
Katalogkennung: falls nicht angegeben, wird die Default-Catid der Benutzerkennung angenommen.
userid
Benutzerkennung: falls nicht angegeben, wird die Benutzerkennung des SET-LOGON-PARAMETERS- bzw. des LOGON-Kommandos angenommen.
dateiname
vollqualifizierter Dateiname
KEYLEN = (keylen1 [,keylen2,...] )
vereinbart für jeden anzulegenden Sekundärschlüssel (Operand KEYNAME) die Länge (in Byte). „keylen“ ist eine beliebige ganze Zahl mit 1 <= keylen <= 127.
KEYPOS und KEYLEN sind so zu wählen, dass der Sekundärschlüssel
auch im kürzesten Satz der Datei noch vollständig enthalten ist und
ganz in einem Datenblock liegt und nicht in einen Überlaufblock hineinragt.
Die runden Klammern in dieser Angabe können weggelassen werden, wenn die Liste nur eine Spezifikation für KEYLEN enthält. Die Angabe einer Liste ist nur für VERSION=2 zulässig, für VERSION=1 ist nur eine Angabe ohne Klammern erlaubt.
KEYNAME = (keyname1 [,keyname2,...] )
legt den Namen der anzulegenden Sekundärschlüssel fest. In der Liste dürfen maximal 30 Namen angegeben werden, wobei zu beachten ist. dass für eine NK-ISAM-Datei maximal 30 Sekundärschlüssel insgesamt erzeugt werden können.
Der Name darf nicht bereits für einen anderen Sekundärschlüssel vereinbart sein. „keyname“ darf bis zu acht Zeichen lang sein und alle Buchstaben und Ziffern sowie die Sonderzeichen „$“, „#“ und „@“ enthalten. „keyname“ muss mit einem Buchstaben oder einem Sonderzeichen beginnen.
Die runden Klammern in dieser Angabe können weggelassen werden, wenn die Liste nur einen Namen enthält. Die Angabe einer Liste ist nur für VERSION=2 zulässig, für VERSION=1 ist nur eine Angabe ohne Klammern erlaubt.
KEYPOS = (keypos1 [,keypos2,...] )
gibt für jeden anzulegenden Sekundärschlüssel (Operand KEYNAME) die Position des ersten Zeichens im Datensatz an.
Für „keypos“ ist eine beliebige ganze Zahl mit 1 <= keypos <= 32496 erlaubt. Bei Sätzen variabler Länge müssen 4 Byte für das Satzlängen- und Steuerfeld berücksichtigt werden.
KEYPOS und KEYLEN sind so zu wählen, dass der Sekundärschlüssel
auch im kürzesten Satz der Datei noch vollständig enthalten ist und
ganz in einem Datenblock liegt und nicht in einen Überlaufblock hineinragt.
Die runden Klammern in dieser Angabe können weggelassen werden, wenn die Liste nur eine Spezifikation für KEYPOS enthält. Die Angabe einer Liste ist nur für VERSION=2 zulässig, für VERSION=1 ist nur eine Angabe ohne Klammern erlaubt.
LINK = linkname1
Legt den Dateikettungsnamen der Datei fest, für die der Sekundärschlüssel vereinbart werden soll. Zum Programmablauf muss diesem Dateikettungsnamen eine NK-ISAM-Datei zugeordnet werden. Sie muss zum Zeitpunkt des CREAIX-Aufrufs mindestens einmal im Modus OUTPUT oder OUTIN eröffnet worden sein und darf keine mehrfach auftretenden Primärschlüsselwerte, keine logischen Markierungen und keine Wertmarkierungen enthalten. „linkname1“ darf bis zu acht Zeichen lang sein. Soll der Dateikettungsname über die Kommandoschnittstelle ansprechbar sein, muss er dem Datentyp <structured_name 1..8> entsprechen (siehe Handbuch „Kommandos“ [3]).
MACID
legt jeweils das zweite bis einschließlich vierte Zeichen der Feldnamen und Equates fest, die bei der Makroauflösung generiert werden.
Voreinstellung: MACID = ISS
= macid
„macid“ ist eine drei Zeichen lange Zeichenfolge, die jeweils das zweite bis vierte Zeichen der generierten Feldnamen und Equates festlegt.
PARAM
bezeichnet die Adresse der Operandenliste und wird nur in Verbindung mit MF=E ausgewertet (siehe auch "Typen von Makroaufrufen").
= adr
adr ist die symbolische Adresse (der Name) der Operandenliste.
= (r)
r ist die Nummer des Registers, das die Adresse der Operandenliste enthält. Vor dem Makroaufruf muss das Register mit diesem Adresswert geladen werden.
PREFIX
legt das jeweils erste Zeichen der Feldnamen und Equates fest, die bei der Makroauflösung generiert werden.
Voreinstellung: PREFIX = D
= pre
„pre“ ist ein Zeichen langes Präfix, mit dem die generierten Feldnamen und Equates beginnen sollen.
SORTLNK = linkname2
Legt den Dateikettungsnamen einer Arbeitsdatei für das Sortierprogramm fest. Diese Arbeitsdatei wird nur benutzt, wenn der virtuelle Adressraum nicht zum Sortieren der Einträge für den Sekundärindexblock ausreicht.
Wenn eine Arbeitsdatei zum Sortieren benötigt wird und SORTLNK nicht angegeben oder dem Dateikettungsnamen beim Programmablauf keine Datei zugeordnet ist, so legt der Makro eine Arbeitsdatei mit dem Namen DISWORK.tsn an (tsn: TSN des Auftrags, der den Makro aufruft).
„linkname2“ darf bis zu acht Zeichen lang sein, und muss nach den Regeln für Dateinamen aus Buchstaben, Ziffern und Sonderzeichen gebildet werden.
VERSION
gibt die Version des generierten Makros CREAIX an.
= 1
Es wird die „alte“ Makroversion generiert.
= 2
Es wird die ab BS2000/OSD-BC V3.0 gültige Version des Makros CREAIX generiert.
Hinweise zur Programmierung
Die D-Form und C-Form des Makros generieren Feldnamen und EQU-Anweisungen für Returncodes. Sie beginnen mit der Zeichenfolge DISS..., die durch die Operanden PREFIX und MACID modifiziert werden kann.
Ist bei der D-Form keine symbolische Adresse angegeben, wird der DSECT-Name DISCRAIX generiert, wobei das erste Zeichen durch eine PREFIX-Angabe modifiziert wird.
Bei der Expansion des Makros CREAIX wird in der Parameterliste ein Feld mit dem Namen KEY# (mit Standard-Präfix DISS oder entsprechend verändert durch die Operanden PREFIX und MACID) erzeugt. Dieses Feld enthält die Anzahl der anzulegenden Sekundärindizes (maximal 30), wobei die Versorgung durch die Expansion des Makros erfolgt. Wenn die Parameterliste allerdings erst zur Programm-Laufzeit dynamisch aufgebaut wird, muss das Feld KEY# vom Programm explizit versorgt werden.
Beim Auftreten eines Fehlers enthält die Parameterliste den Index des Sekundärindex in der angegebenen Liste, bei dem dieser Fehler auftrat. Außerdem wird ein eventuell aufgetretener DMS-Fehler ebenfalls in der Parameterliste hinterlegt (der Name des Feldes, das den Index des Sekundärindex beinhaltet, bei dem ein Fehler auftrat, lautet DISAERR bzw. <xxxy>AERR je nach PREFIX und MACID).
Für eine NK-ISAM-Datei können bis zu maximal 30 Sekundärindizes insgesamt erzeugt werden. Es ist also darauf zu achten, dass einerseits die im Makro spezifizierte Liste der Namen der zu definierenden Sekundärindizes höchstens 30 Elemente umfasst. Andererseits darf die Summe aus bereits existierenden und neu zu erzeugenden Sekundärindizes ebenfalls nicht größer als 30 sein (beide Fälle führen zu einem entsprechenden Returncode).
Es ist darauf zu achten, dass für eine Parameterliste der Wert von VERSION konsistent für Aufrufe mit unterschiedlichen MF-Formaten versorgt wird.
Returncodes
Die vom Makro CREAIX ausgegebenen Returncodes werden im Standardheader der Operandenliste hinterlegt. Der Standardheader muss vor der Generierung der DSECT für die CREAIX-Parameterliste definiert werden.
Die mit der C- oder D-Form des Makros generierten Returncodes beginnen standardmäßig mit der Zeichenfolge DISS, diese kann im ersten Zeichen durch die Angabe von PREFIX, in den Zeichen 2 bis 4 durch die Angabe von MACID entsprechend modifiziert werden.
Standardheader: 00bbaaaa
Über die Ausführung des Makros CREAIX wird im Standardheader folgender Returncode übergeben (bb = SUBCODE1, aaaa = MAINCODE):
X'bb' | X'aaaa' | Erläuterung |
X'00' | X'0000' | Funktion erfolgreich ausgeführt. |
X'01' | X'0001' | Die Operandenliste ist nicht verfügbar. |
X'40' | X'0003' | Die angegebene Katalogkennung existiert nicht. |
X'40' | X'0004' | Auf den Katalog kann nicht zugegriffen werden. |
X'01' | X'0005' | Die Operandenliste enthält einen ungültigen Namen. |
X'40' | X'0006' | Die angegebene Datei enthält DUPEKYs. |
X'40' | X'0007' | Der zu definierende Sekundärschlüssel existiert bereits. |
X'01' | X'0009' | ungültige Angabe für KEYLEN. |
X'40' | X'000A' | Die angegebene Datei enthält Logische oder Wertmarkierungen |
X'20' | X'000B' | Systemfehler. |
X'40' | X'000C' | Der Benutzeradressraum ist zu klein. |
X'01' | X'000D' | ungültige Angabe für KEYPOS. |
X'40' | X'000E' | Der Kontrollblock der Datei ist fehlerhaft. |
X'40' | X'000F' | Ein Satz in der angegebenen Datei ist zu klein für den zu definierenden Sekundärschlüssel. |
X'40' | X'0010' | Es sind bereits 30 Sekundärschlüssel für die Datei definiert. |
X'40' | X'0011' | Die Datei enthält unvollständige Sekundärindexblöcke. |
X'40' | X'0012' | Der ISAM-Pool ist überlastet. |
X'40' | X'0013' | Der Sekundärschlüssel ist bereits mit anderen Attributen definiert. |
X'40' | X'0014' | Unterbrechung durch CANCEL |
X'40' | X'0015' | Unterbrechung durch BREAK |
X'01' | X'0017' | In der Operandenliste wurde keine Datei spezifiziert. |
X'40' | X'0018' | Zum Zeitpunkt des Makroaufrufs ist SHARUPD=YES eingestellt. |
X'40' | X'0019' | Der Dateikettungsname ist fehlerhaft. |
X'40' | X'001A' | Obwohl DUPKEY=NO gefordert ist, kommen gleiche Werte des Sekundärschlüssels in verschiedenen Sätzen vor. |
X'40' | X'001B' | ungültiges Listenelement |
X'40' | X'001C' | ungültige Anzahl von Sekundärindizes in der Liste |
X'40' | X'0040' | OPEN-Fehler. |
X'40' | X'0041' | CLOSE-Fehler. |
X'40' | X'0042' | Beim Schreiben der Sekundärindexblöcke trat ein Fehler auf. |
X'40' | X'0043' | Beim Lesen der Datei trat ein Fehler auf. |
X'40' | X'0044' | Die Datei ist keine NK-ISAM-Datei. |
X'40' | X'0081' | Beim Sortieren der Sekundärindexeinträge trat ein DVS-Sonderzustand ein. |
X'40' | X'0082' | Beim Sortieren der Sekundärindexeinträge trat ein interner Fehler auf. |
X'01' | X'FFFF' | Linkage-Fehler (Funktion nicht unterstützt) |
X'02' | X'FFFF' | Linkage-Fehler (Funktion nicht verfügbar) |
X'03' | X'FFFF' | Linkage-Fehler (Version nicht unterstützt) |
Weitere Returncodes, deren Bedeutung durch Konvention makroübergreifend festgelegt ist, können der Tabelle auf "Standardheader" (Standardheader) entnommen werden.
Das aufrufende Programm wird beendet, wenn bezüglich der Parameterliste folgende Fehler auftreten:
Die Liste ist dem Aufrufer nicht zugewiesen.
Die Liste ist nicht auf Wortgrenze ausgerichtet.
Die Liste ist gegen Schreibzugriff geschützt.