Makrotyp: S-Typ (E-Form/L-Form/D-Form/C-Form/M-Form) (siehe "Typen von Makroaufrufen")
Der Makro SHOPLNK informiert über die Zuordnung von ISAM-Pools zu ISAM-Pool-Kettungsnamen. Hierzu kann der Anwender entweder den Pool-Kettungsnamen angeben oder den Namen des ISAM-Pools.
Ein ISAM-Pool-Kettungsname kann jedem ISAM-Pool zugeordnet werden, sofern ein Anschluss zu diesem ISAM-Pool besteht, unabhängig vom Gültigkeitsbereich des betroffenen ISAM-Pools und vom Host-Rechner, an dem der betroffene ISAM-Pool vorhanden ist.
Format
Operation | Operanden |
|
|
| |
| |
|
Operandenbeschreibung
AREA
Gibt einen Ausgabebereich an, in den die Ausgabeliste übertragen wird. Uneingeschränkter Zeichenvorrat und uneingeschränkte Länge.
Bei der Form MF=L kann nur der Operandenwert adr angegeben werden.
Voreinstellung: X'FFFFFFFF'
= adr
Symbolische Adresse eines Feldes, das den Namen des Ausgabereiches enthält.
= (r)
Register, das die Adresse eines Feldes enthält, in dem der Name des Ausgabebereiches hinterlegt ist.
CATID
Gibt die Katalogkennung des PVS an, dem der ISAM-Pool, zu dem Pool-Kettungsnamen ermittelt werden sollen, beim Kreieren zugeordnet wurde (nicht von Bedeutung bei Angabe des Parameters NAME=*ALL).
Bei der Form MF=L kann nur der Operandenwert 'name' angegeben werden.
Voreinstellung: | die Default-PVS-Id des Auftrages (DEFAULT-PUBSET im Benutzerkatalogeintrag) bzw. die Home-PVS-Id (abhängig von der Einstellung des Systemparameters ISPLDEFC). |
= 'name'
Name eines Feldes mit der Katalogkennung des Pubsets. 4 Zeichen lang.
= adr
Symbolische Adresse eines Feldes mit der Katalogkennung des Pubsets.
= (r)
Register, das die Adresse eines Feldes mit der Katalogkennung des Pubsets enthält.
LINK = *ALL
Die Zuordnung aller vom Aufrufer definierten Pool-Kettungsnamen zu ISAM-Pools werden ermittelt.
= name
Gibt den ISAM-Pool-Kettungsnamen an, dessen Zuordnung zu einem ISAM-Pool ermittelt werden soll.
= adr
ist die symbolische Adresse eines Feldes, das den Link-Namen enthält.
= (r)
ist das Register, das die Adresse des LINK-Namens enthält.
MACID
wird nur in Verbindung mit MF=C ausgewertet und legt jeweils das zweite bis einschließlich vierte Zeichen der Feldnamen und Equates fest, die bei der Makroauflösung generiert werden.
Voreinstellung: MACID = ISL
= macid
„macid“ ist eine drei Zeichen lange Zeichenfolge, die jeweils das zweite bis vierte Zeichen der generierten Feldnamen und Equates festlegt.
MF
die Formen des MF-Operanden sind detailliert im Anhang ("Typen von Makroaufrufen") beschrieben.
NAME
Gibt den Namen an, mit dem der ISAM-Pool, für den ISAM-Pool-Kettungsnamen ermittelt werden sollen, angelegt wurde. Der gewünschte ISAM-Pool wird eindeutig bestimmt über den angegebenen Namen, die Katalogkennung (CATID) und den Geltungsbereich (SCOPE).
Bei der Form MF=L können nur die Operandenwerte 'name'/*ALL angegeben werden.
= *ALL
Für alle vom Aufrufer erzeugten ISAM-Pools sollen die Pool-Kettungsnamen ermittelt werden.
= 'name'
Name des ISAM-Pools für den ISAM-Pool-Kettungsnamen ermittelt werden sollen.
= adr
Symbolische Adresse eines Feldes, das den Namen des ISAM-Pools oder *ALL enthält.
= (r)
Register, das die Adresse eines Feldes enthält, in dem der Name des ISAM-Pools oder *ALL hinterlegt ist.
SCOPE
Geltungsbereich des angegebenen ISAM-Pools, über den Informationen ausgegeben werden sollen. Wurde NAME=*ALL angegeben, werden Angaben beim Operanden SCOPE ignoriert.
Bei der Form MF=L können nur die Operandenwerte *TASK/*USERID/*HOST angegeben werden.
= *TASK
Für den tasklokalen ISAM-Pool mit dem angegebenen Namen sollen Pool-Kettungsnamen ausgegeben werden
= *USERID
= *USERGROUP
Die bis BS2000/OSD-BC V6.0A vorhandenen Geltungsbereiche SCOPE=USERID und SCOPE=USERGROUP werden aus Kompatibilitätsgründen noch akzeptiert, intern jedoch auf SCOPE=HOST (taskübergreifender ISAM-Pool) abgebildet.
Es werden aber jeweils nur die ISAM-Pools angezeigt, die mit dem angegebenen SCOPE angelegt wurden.
= *HOST
Für den taskübergreifenden ISAM-Pool mit dem angegebenen Namen sollen Pool-Kettungsnamen ausgegeben werden
= adr
4 Byte lange symb. Adresse eines Feldes, das den Scope des ISAM-Pools enthält.
= (r)
Ist ein Register mit der Adresse, an der der Scope des ISAM-Pools hinterlegt ist.
SIZE
Gibt die Länge des Ausgabebereiches an.
Bei der Form MF=L können nur die Operandenwerte zahl/*equ angegeben werden.
Voreinstellung: X'00000000'
= zahl
numerische Zahl, die die Länge des Ausgabebereiches angibt: 100 <= zahl <= 10000.
= adr
ist die 4 Byte lange symbolische Adresse für die Länge des Ausgabebereiches.
= (r)
Register, das die Länge des Ausgabebereiches enthält.
= *equ
EQUATE mit der Länge Ausgabereiches
XPAND
Steuerungs-Operand nur für MF=C und MF=D:
Es wird festgelegt, welche Struktur zu expandieren (erzeugen) ist. Angaben bei diesem Operanden werden bei anderen MF-Werten ignoriert.
= PARAM
Das Layout der Parameterliste wird expandiert.
= DESCHDR
Das Layout des Headers des Ausgabebereiches wird expandiert.
= LINKDESC
Das Layout eines Pool-Link-Deskriptors wird expandiert.
Returncodes
Die Returncodes werden im Header der jeweiligen Parameterliste hinterlegt:
Der Main Code in einem Halbwort mit dem Namen DISLMRET.
Der Subcode1 steht in einem Byte mit dem Namen DISLSR1. Er beschreibt Fehlerklassen, die es dem Aufrufer ermöglichen sollen, auf Fehlerklassen zu reagieren.
Der Aufrufer kann sich sowohl am Maincode als auch am Subcode1 orientieren, wobei eine Auswertung des Subcode1 jedoch vorzuziehen ist: bei der Erweiterung der Maincodes für einen Makro sind Auswertungen nicht betroffen, wenn sie ausschließlich auf Fehlerklassen reagieren.Der Subcode2 hat immer den Wert X'00'.
Falls Returncodes nicht im Header eines Makros abgelegt werden können, beispielsweise wenn dieser nicht zugreifbar ist, so wird das aufrufende Programm mit einer entsprechenden Fehlermeldung beendet.
Im Falle des Returncodes „interner Systemfehler beim Aufruf einer Systemfunktion“ enthält das Feld DISL.SYCD in der Parameterliste des jeweiligen Makros einen genaueren Code zur Diagnose (Werte: siehe Inserts bei der entsprechenden Message).
Ein Makro-Aufruf mit MF=D oder MF=C generiert zusätzlich zu den Feldnamen auch die EQU-Anweisungen für die Returncodes.
In der folgenden Übersicht werden für den Makro SHOPLNK die Returncodes in tabellarischer Form dargestellt. Die angegebenen Namen der EQU-Anweisungen sind links durch den String DISL zu ergänzen, wobei DISL modifiziert werden kann durch die Parameter PREFIX=prefix bzw. MACID=macid (siehe Operandenbeschreibung).
Standardheader: ccbbaaaa
Über die Ausführung des Makros SHOPLNK wird im Standardheader folgender Returncode übergeben (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'bb' | X'aaaa' | Erläuterung |
X'00' | X'0000' | Funktion erfolgreich ausgeführt. |
X'01' | X'FFFF' | Der Header ist fehlerhaft, z.B. nicht korrekt initialisiert. |
X'02' | X'FFFF' | Linkage Fehler (Function not available) |
X'03' | X'FFFF' | Linkage Fehler ( Version not supported) |
X'01' | X'0001' | Parameterliste nicht zugreifbar. |
X'01' | X'0002' | Parameterfehler. |
X'20' | X'0005' | interner Systemfehler beim Aufruf einer Systemfunktion |
X'40' | X'0008' | Der angegebene ISAM-Pool-Link-Name existiert nicht. |
X'40' | X'0009' | Der Aufrufer hat keinen ISAM-Pool-Link-Namen definiert |
X'82' | X'000B' | kein virtueller Speicherplatz verfügbar. |
Weitere Returncodes, deren Bedeutung durch Konvention makroübergreifend festgelegt ist, können der Tabelle im Kapitel "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.
Layout der Operandenliste
Makroauflösung mit MF=D und Standardwerten für PREFIX und MACID:
SHOPLNK MF=D 1 STACK PRINT 1 PRINT NOGEN 2 *,##### PREFIX=D, MACID=ISL ##### 1 #INTF INTNAME=SHOPLNK,REFTYPE=REQUEST,INTCOMP=002 1 DISLPLA DS 0F BEGIN of PARAMETERAREA _INOUT 1 FHDR MF=(C,DISL),EQUATES=YES 2 DS 0A 2 DISLFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER 2 * 2 DISLIFID DS 0A 0 INTERFACE IDENTIFIER 2 DISLFCTU DS AL2 0 FUNCTION UNIT NUMBER 2 * BIT 15 HEADER FLAG BIT, 2 * MUST BE RESET UNTIL FURTHER NOTICE 2 * BIT 14-12 UNUSED, MUST BE RESET 2 * BIT 11-0 REAL FUNCTION UNIT NUMBER 2 DISLFCT DS AL1 2 FUNCTION NUMBER 2 DISLFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER 2 * 2 DISLRET DS 0A 4 GENERAL RETURN CODE 2 * 2 * GENERAL_RETURN_CODE CLEARED (X'00000000') MEANS 2 * REQUEST SUCCESSFUL PROCESSED AND NO ADDITIONAL INFORMATION 2 * 2 DISLSRET DS 0AL2 4 SUB RETURN CODE 2 DISLSR2 DS AL1 4 SUB RETURN CODE 2 2 * ALWAYS CLEARED (X'00') IF MAIN_RETURN_CODE IS X'FFFF' 2 * Standard subcode2 values as defined by convention: 2 DISLR2OK EQU X'00' All correct, no additional info 2 DISLR2NA EQU X'01' Successful, no action was necessary 2 DISLR2WA EQU X'02' Warning, particular situation 2 DISLSR1 DS AL1 5 SUB RETURN CODE 1 2 * 2 * GENERAL INDICATION OF ERROR CLASSES 2 * 2 * CLASS A X'00' FUNCTION WAS SUCCESSFULLY PROCESSED 2 * CLASS B X'01' - X'1F' PARAMETER SYNTAX ERROR 2 * CLASS C X'20' INTERNAL ERROR IN CALLED FUNCTION 2 * CLASS D X'40' - X'7F' NO CLASS SPECIFIC REACTION POSSIBLE 2 * CLASS E X'80' - X'82' WAIT AND RETRY 2 * 2 DISLRFSP EQU X'00' FUNCTION SUCCESSFULLY PROCESSED 2 DISLRPER EQU X'01' PARAMETER SYNTAX ERROR 2 * 3 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'01' - X'1F' 2 DISLRFNS EQU X'01' CALLED FUNCTION NOT SUPPORTED 2 DISLRFNA EQU X'02' CALLED FUNCTION NOT AVAILABLE 2 DISLRVNA EQU X'03' INTERFACE VERSION NOT SUPPORTED 2 * 2 DISLRAER EQU X'04' ALIGNMENT ERROR 2 DISLRIER EQU X'20' INTERNAL ERROR 2 DISLRCAR EQU X'40' CORRECT AND RETRY 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'40' - X'7F' 2 DISLRECR EQU X'41' SUBSYSTEM (SS) MUST BE CREATED 2 * EXPLICITELY BY CREATE-SS 2 DISLRECN EQU X'42' SS MUST BE EXPLICITELY CONNECTED 2 * 2 DISLRWAR EQU X'80' WAIT FOR A SHORT TIME AND RETRY 2 DISLRWLR EQU X'81' " LONG " 2 DISLRWUR EQU X'82' WAIT TIME IS UNCALCULABLY LONG 2 * BUT RETRY IS POSSIBLE 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'80' - X'82' 2 DISLRTNA EQU X'81' SS TEMPORARILY NOT AVAILABLE 2 DISLRDH EQU X'82' SS IN DELETE / HOLD 2 * 2 DISLMRET DS 0AL2 6 MAIN RETURN CODE 2 DISLMR2 DS AL1 6 MAIN RETURN CODE 2 2 DISLMR1 DS AL1 7 MAIN RETURN CODE 1 2 * 2 * SPECIAL LAYOUT OF LINKAGE_MAIN_RETURN_CODE (YYYY IN X'00XXYYYY') 2 * 2 DISLRLNK EQU X'FFFF' LINKAGE ERROR / REQ. NOT PROCESSED 2 DISLFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH 2 * 1 DISLOK EQU X'0000' FUNCTION SUCCESSFUL PROCESSED 1 DISLNPAR EQU X'0001' PARAMETERLIST NOT ACCESSIBLE 1 DISLPERR EQU X'0002' PARAMETER ERROR 1 DISLSYSE EQU X'0005' INTERNAL SYSTEM ERROR 1 DISLLLNE EQU X'0008' SPECIFIED POOL LINK NAME NOT FOUND 1 DISLNOLI EQU X'0009' NO ISAM POOL LINK EXISTING 1 DISLNOSP EQU X'000B' NO MEMORY AVAILABLE 1 DISLNUGR EQU X'000C' NO USEGROUP DEFINED 1 DISLINOP EQU X'001F' SSTA INOP 1 DISLSSER EQU X'0020' SSTA INTERNAL ERROR 1 DISLMEMR EQU X'0021' SSTA MEMORY ERROR 1 DISLOPSR EQU X'0022' SSTA OPS ERROR 1 DISLOPME EQU X'0023' SSTA OPS MEMORY ERROR 1 * 1 * 1 DISLPLNK DS CL8 LINK-NAME 1 DISLPNAM DS CL8 POOL-NAME 1 DISLCID DS CL4 CATALOG-IDENTIFIER 1 * 1 DISLSCOP DS XL1 SCOPE 1 DISLTASK EQU X'00' = TASK 1 DISLUSID EQU X'01' = USERID 1 DISLHOST EQU X'02' = HOST-SYSTEM 1 DISLUSGR EQU X'03' = USERGROUP 1 * 1 DISLSYCD DS XL1 SYSTEM-ERROR-CODE 1 * 1 DISLADDR DS A ADDRESS OF OUTPUT-AREA 1 DISLSIZE DS F SIZE OF OUTPUT-AREA 1 * 1 DISL# EQU *-DISLPLA LENGTH of PARAMETERAREA
Format des Ausgabebereiches
Der Makro SHOPLNK liefert dem Aufrufer die Zuordnungen von ISAM-Pools zu ISAM-Pool-Kettungsnamen in seinem Ausgabe-Bereich. Dieser beginnt zunächst mit einem Verwaltungs-Header der Länge 16 Byte.
Der Verwaltungs-Header des Ausgabe-Bereiches wird generiert durch die Angabe des Steuer-Operanden XPAND=DESCHDR beim Aufruf des Makros SHOPLNK mit dem Steuer-Operanden MF=D oder MF=C:
1 DISLADMH DS 0F VERWALTUNGS-HEADER-LAYOUT 1 DISLLLG DS F ANZAHL UEBERTRAGENER BYTES 1 DISLLCLG DS F LAENGE DER GESAMT-INFORMATION 1 DISLL#LN DS H ANZAHL BETROFFENER LINKNAMEN 1 DISLLIND DS XL1 UEBERTRAGUNGS-INDIKATOR 1 DISLLCOM EQU X'00' INFORMATION VOLLSTAENDIG 1 DISLLPAR EQU X'01' INFORMATION UNVOLLSTAENDIG 1 DISLLRES DS CL5 NICHT VERWENDET 1 DISLLLEN EQU *-DISLADMH LAENGE DES HEADERS
Ein Eintrag mit Informationen wird expandiert durch die Angabe des Parameters XPAND=LINKDESC beim Aufruf des Makros SHOPLNK mit dem Steuer-Operanden MF=C oder MF=D:
1 DISLLDDS DS 0F POOL-LINK-DESCRIPTOR-LAYOUT 1 DISLLNAM DS CL8 NAME DES POOL-LINKS 1 DISLPONA DS CL8 NAME DES ZUGEORDNETEN ISAM-POOLS 1 DISLLCID DS CL4 NAME DES ZUGEORDNETEN PVS 1 DISLLSCO DS XL1 SCOPE DES ISAM-POOLS 1 DISLLTSK EQU X'00' SCOPE = TASK 1 DISLLUSR EQU X'01' SCOPE = USERID 1 DISLLHOS EQU X'02' SCOPE = HOST 1 DISLLUGR EQU X'03' SCOPE = USERGROUP 1 DISLLUID DS CL8 USERID BEI SCOPE = *USERID 1 * GRUPPENNAME BEI SCOPE = *USERGROUP 1 DISLLRSV DS CL3 NICHT VERWENDET 1 DISLLLNG EQU *-DISLLDDS LAENGE DES ISAM-POOL-DESCR.
Erläuterungen zu den einzelnen Feldern des Ausgabebereiches
Verwaltungsheader
Der Verwaltungs-Header (Länge 16 Byte) enthält folgende Informationen:
die Anzahl der Bytes, die in den Ausgabebereich übertragen wurde (Länge: 4 Byte),
die Anzahl der Bytes, aus denen die gesamte Information besteht (Länge: 4 Byte; dies ist dann für den Aufrufer des Makros von Bedeutung, wenn der Ausgabebereich zu klein ist: in diesem Falle muss der Aufrufer des Makros den Ausgabebereich in dieser Länge (mindestens) zur Verfügung stellen),
die Anzahl der ISAM-Pool-Kettungsnamen, für die im Ausgabebereich die Zuordnung zu ISAM-Pools ermittelt wurde (Länge: 2 Byte),
ein Indikator der Länge 1 Byte, der angibt, ob die in den Ausgabebereich übertragene Information vollständig ist, oder ob auf Grund eines zu kurzen Ausgabebereiches nur ein Teil der gewünschten Informationen geliefert werden konnte, wobei gilt:
X'00': Information ist komplett,
X'01': Information wurde abgeschnitten und ist unvollständig;
(im letzteren Falle muss der Aufrufer einen größeren Ausgabebereich zur Verfügung stellen, um die komplette Information zu erhalten; die Länge des größeren Ausgabebereiches ist dann dem zweiten Wort des Verwaltungs-Headers zu entnehmen),die restlichen 5 Byte werden nicht verwendet.
Deskriptorbereich
Zur Identifikation eines ISAM-Pools in eindeutiger Weise benötigt man den Namen des ISAM-Pools sowie die CATID des Host-Rechners, an dem der ISAM-Pool vorhanden ist, und außerdem den Gültigkeitsbereich des ISAM-Pools. Der Ausgabebereich für den Makro SHOPLNK enthält Einträge in der Länge von 32 Byte, die zunächst einen ISAM-Pool-Kettungsnamen enthalten, gefolgt von einem ISAM-Pool-Descriptor mit den oben genannten Informationen. Somit sind in einem Eintrag im Ausgabebereich folgende Informationen enthalten:
der Name eines ISAM-Pool-Kettungsnamens in der Länge von 8 Byte (abdruckbar),
der Name des zugeordneten ISAM-Pools in der Länge von 8 Byte (abdruckbar),
die CATID des Host-Rechners, auf dem der betroffene ISAM-Pool vorhanden ist, ebenfalls abdruckbar in der Länge von 4 Byte,
den SCOPE (Gültigkeits-Bereich) des betroffenen ISAM-Pools in der Länge 1 Byte, wobei gilt:
X'00': SCOPE = *TASK
X'01': SCOPE = *USERID
X'02': SCOPE = *HOST
X'03': SCOPE = *USERGROUPdie USERID, falls der zugeordnete ISAM-Pool mit dem Attribut SCOPE = USERID versehen ist,
die restlichen 3 Byte werden nicht verwendet.
Der Ausgabebereich, den der Makro SHOPLNK versorgt, hat mit den genannten Strukturen dann den folgenden Aufbau:
HEADER | LINKNAME1 | POOLNAME1 | CATID1 | SCOPE1 | userid | UNUSED LINKNAME2 | POOLNAME2 | CATID2 | SCOPE2 | userid | UNUSED ....... ....... LINKNAMEn | POOLNAMEn | CATIDn | SCOPEn | userid | UNUSED
Das Feld „userid“ enthält Blanks bei SCOPE=TASK oder SCOPE=HOST.
Im Anschluss an den Verwaltungs-Header wird die Zuordnung von ISAM-Pools zu Pool-Kettungsnamen beschrieben; die Anzahl der erstellten Einträge ist im Verwaltungs-Header enthalten.