Mit dem Aufruf SGET (storage GET) lesen Sie Daten von einem Sekundärspeicherbereich in einen Speicherbereich des Teilprogramms. Als Sekundärspeicherbereiche kommen dabei infrage:
der Globale Sekundäre Speicherbereich (GSSB)
der Lokale Sekundäre Speicherbereich (LSSB)
der User-spezifische Langzeitspeicher (ULS)
Falls ein LSSB nicht mehr benötigt wird, kann er durch Angabe von KCOM=RL gleichzeitig gelöscht werden. Der Inhalt eines ULS kann nur durch Schreiben (SPUT) mit KCLA=0 gelöscht werden.
Ein GSSB muss mit einem eigenen Aufruf (SREL) gelöscht werden; er ist bis zum Ende der Transaktion bzw. des Vorgangs gesperrt. Siehe hierzu die Beschreibung des SREL-Aufrufs.
Mit dem Aufruf UNLK kann ein GSSB oder ULS explizit entsperrt werden.
Unix-, Linux- and Windows-Systeme
In UTM-Cluster-Anwendungen stehen GSSB oder ULS Cluster-weit zur Verfügung.
Versorgen des KDCS-Parameterbereichs (1. Parameter)
Die folgende Tabelle zeigt die notwendigen Angaben im KDCS-Parameterbereich.
Funktion des Aufrufs | Einträge im KDCS-Parameterbereich | ||||
|---|---|---|---|---|---|
KCOP | KCOM | KCLA | KCRN | KCUS | |
Lesen aus einem LSSB | "SGET" | "KP" | Länge | Name des LSSB | - |
Lesen aus einem LSSB und Löschen des LSSB | "SGET" | "RL" | Länge | Name des LSSB | - |
Lesen aus einem GSSB (mit Sperren des GSSB) | "SGET" | "GB" | Länge | Name des GSSB | - |
Lesen aus einem ULS (mit Sperren des ULS) | "SGET" | "US" | Länge | Blockname | Benutzerkennung/LSES-Name/Association-Name/Leerzeichen |
Bei KCOM = US müssen alle nicht verwendeten Felder des KDCS-Parameterbereichs mit binär null versorgt werden.
Versorgen des 2. Parameters
Hier stellen Sie die Adresse des Nachrichtenbereichs bereit, in den openUTM die Nachricht lesen soll.
Versorgen der Parameter | |
Feldname im KDCS-Parameterbereich | Inhalt |
"SGET" | |
"KP"/"RL"/"GB"/"US" | |
Länge in Byte | |
Name des Bereichs | |
Benutzerkennung/LSES-Name/Association-Name/Leerzeichen | |
KDCS-Aufruf | |
KDCS-Parameterbereich | Nachrichtenbereich |
C/C++-Makroaufrufe | |
Parameter | |
KDCS_SGETKP/KDCS_SGETRL/KDCS_SGETGB | (nb,kcla,kcrn) |
KDCS_SGETUS | (nb,kcla,kcrn,kcus) |
Rückgaben von openUTM | |
|---|---|
Inhalt | |
Daten | |
Feldname im KB-Rückgabebereich | |
tatsächliche Blocklänge | |
Returncode | |
interner Returncode | |
In den KDCS-Parameterbereich tragen Sie für den SGET-Aufruf ein:
KCOP
im Feld KCOP den Operationscode SGET.
KCOM
im Feld KCOM:
KP (keep) zum Lesen eines LSSBs - der Bereich bleibt erhalten
RL (release) zum Lesen und Löschen eines LSSBs
GB zum Lesen eines GSSBs
US zum Lesen eines Blocks eines ULS
KCLA
im Feld KCLA die Länge, in der die Daten in den Nachrichtenbereich übertragen werden sollen.
KCRN
im Feld KCRN den Namen des LSSB/GSSB bzw. des ULS-Blocks, aus dem gelesen werden soll.
KCUS
im Feld KCUS die Benutzerkennung/Session/Association, wenn ein ULS-Block einer fremden Benutzerkennung/Session/Association gelesen werden soll, sonst Leerzeichen (bei Angabe von Leerzeichen wird der ULS-Block des Benutzers/Session/Association gelesen, der den Vorgang gestartet hat).
Wird eine fremde Benutzerkennung/Session/Association in KCUS eingetragen, dann muss die eigene Benutzerkennung/Session/Association administrationsberechtigt sein.
Bei KCOM = KP/RL/GB: irrelevant.
Beim KDCS-Aufruf geben Sie an:
1. Parameter
als 1. Parameter: Die Adresse des KDCS-Parameterbereichs.
2. Parameter
als 2. Parameter: die Adresse des Nachrichtenbereichs, in den openUTM die Nachricht einlesen soll. Die Adresse des Nachrichtenbereichs müssen Sie auch dann angeben, wenn Sie in KCLA die Länge 0 eintragen.
Makronamen
Wie Sie Makroaufrufe für C/C++ nutzen, ist in Abschnitt „C/C++-Makroschnittstelle" ausführlich beschrieben.
openUTM gibt zurück:
Nachrichtenbereich
im angegebenen Nachrichtenbereich die gewünschten Daten.
KCRLM
in KCRLM die tatsächliche Länge der Daten im LSSB/GSSB/ULS (in Bytes). Damit können Sie Abweichungen von der Angabe in KCLA feststellen (wichtig, wenn KCLA kleiner angegeben wurde).
Ausnahme: Bei KCLA = 0 wird immer KCRLM = 0 zurückgegeben.
KCRCCC
im Feld KCRCCC den KDCS-Returncode, siehe nächste Seite.
KCRCDC
im Feld KCRCDC den internen Returncode von openUTM (siehe openUTM-Handbuch „Meldungen, Test und Diagnose“).
KDCS-Returncodes im Feld KCRCCC beim SGET-Aufruf
Im Programm sind auswertbar:
000 | Die Operation wurde ausgeführt. |
14Z | Unter dem in KCRN angegebenen Namen ist kein Bereich vorhanden (nur bei KP, RL, GB). |
40Z | Das System kann die Operation nicht ausführen (Generierungs- bzw. Systemfehler, Deadlock, Timeout), siehe KCRCDC. |
41Z | Der Aufruf wurde im ersten Teil des Anmelde-Vorgangs abgesetzt, obwohl dies in der Generierung nicht erlaubt wurde. bei KCOM=US: der Aufruf wurde im ersten Teil des Anmelde-Vorgangs oder im Anmelde-Vorgang nach einem SIGN ON und vor dem PEND PS Aufruf abgesetzt. |
42Z | Der Eintrag in KCOM ist ungültig. |
43Z | Die Längenangabe in KCLA ist negativ bzw. ungültig. |
44Z | Name in KCRN ungültig. Er ist ungültig, wenn er nur aus Leerzeichen oder nur aus binär null besteht oder nicht generiert ist (bei ULS). |
46Z | Die Angabe in KCUS ist ungültig. |
47Z | Der Nachrichtenbereich fehlt oder ist in der angegebenen Länge nicht zugreifbar. |
49Z | Der Inhalt nicht verwendeter Felder des KDCS-Parameterbereichs ist ungleich binär null (nur bei KCOM = US). |
Ein weiterer Returncode ist dem DUMP zu entnehmen:
71Z | In diesem Programm wurde kein INIT gegeben. |
Eigenschaften des SGET-Aufrufs
Der Bereich wird in der tatsächlichen Länge übertragen, höchstens jedoch in der bei KCLA angegebenen Länge. Die tatsächliche Länge der Daten im GSSB, LSSB oder ULS wird im Feld KCRLM zurückgegeben:
Ist die in KCLA angegebene Länge kleiner als die tatsächliche Länge des zu lesenden Satzes, wird rechts abgeschnitten. Im Teilprogramm kann dieses Situation abgefangen werden (KCLA < KCRM).
Ist die in KCLA angegebene Länge größer als die tatsächliche Länge des zu lesenden Satzes (KCLA > KCRLM), ist nach dem SGET-Aufruf der überschüssige Teil des Nachrichtenbereichs undefiniert.
Wird in einem Teilprogramm versucht, die Leseoperation SGET auf einen nicht vorhandenen Speicherbereich durchzuführen, bekommt das Teilprogramm den Returncode 14Z (kein Bereich mit diesem Namen vorhanden).
Wird mit einem SGET auf einen GSSB oder ULS zugegriffen, gilt:
Ein SGET-Aufruf für einen GSSB bzw. ULS-Block sperrt diesen bis zum nächsten Sicherungs- bzw. Rücksetzpunkt (d.h. bis zum PEND SP/RE/FI/FC/RS/ER/FR oder RSET). Wird der Verarbeitungsschritt nach einem SGET-Aufruf in einem Teilprogramm mit einem PEND KP, PGWT KP, PGWT PR oder mit einem PEND PA/PR mit Taskwechsel wegen TAC-Klassensteuerung oder Wartens auf DGET-Nachricht abgeschlossen, bleibt die Zugriffssperre bis zum nächsten
Sicherungspunkt erhalten, außer die Sperre wird vorher durch einen UNLK-Aufruf gelöst.Lesen aus einem nicht vorhandenen GSSB hat die gleiche Wirkung wie Erzeugen eines GSSB mit gleichzeitigem Löschen (SPUT, SREL-Folge), d.h.:
Der Name dieses GSSB bleibt bis zum nächsten Sicherungs- oder
Rücksetzpunkt gesperrt.Ist die generierte maximale Anzahl von GSSBs bereits erreicht, bekommt daher das Teilprogramm den Returncode 40Z mit KCRCDC K804 zurück.
Unix-, Linux- and Windows-Systeme
In einer UTM-Cluster-Anwendung sind für das Lesen aus einem nicht vorhandenen GSSB vier zusätzliche Datei-Zugriffe notwendig (zum Erhöhen und Vermindern des GSSB-Zählers). Daher ist es in UTM-Cluster-Anwendungen aus Performancegründen sinnvoll, etwa zur Serialisierung von Teilprogrammen keinen leeren GSSB, sondern z.B. einen GSSB der Länge 1 zu verwenden.
Wie openUTM reagiert, wenn der gewünschte GSSB oder ULS-Block gesperrt ist, ist in Abschnitt „Verhalten bei gesperrten Speicherbereichen (TLS, ULS und GSSB)" beschrieben.
Wird mit einem SGET auf einen LSSB zugegriffen, gilt:
SGET KP bewirkt, dass der LSSB auch noch in der Folgetransaktion des Vorgangs, d.h. nach dem nächsten PEND RE/SP zur Verfügung steht.
SGET RL liest den LSSB und löscht ihn bei Transaktionsende (d.h. bei PEND RE/SP/FI/FC/RS/ER/FR). Ein zwischenzeitlicher Zugriffsversuch wird mit 14Z zurückgewiesen.
Diese Variante sollten Sie immer dann verwenden, wenn der LSSB nach dem Lesen im laufenden Vorgang nicht mehr benötigt wird.