SPUT Schreiben in einen Sekundärspeicherbereich

Mit einem Aufruf SPUT (storage PUT) schreiben Sie Daten aus einem angegebenen Bereich in einen

• Globalen Sekundären Speicherbereich (GSSB) oder in einen

• Lokalen Sekundären Speicherbereich (LSSB) oder in einen

• User-spezifischen Langzeitspeicher (ULS).

Beachten Sie, dass der Name eines ULS-Blocks bei der Generierung vergeben wird (ULS-Anweisung bei KDCDEF), während Sie die Namen von GSSBs und LSSBs beim SPUT-Aufruf frei wählen können.

Unix-, Linux- und Windows-Systeme
In UTM-Cluster-Anwendungen stehen GSSB oder ULS Cluster-weit zur Verfügung.

Versorgen des 1. Parameters (KDCS-Parameterbereich)

Die folgende Tabelle zeigt die verschiedenen Möglichkeiten und die dafür notwendigen Angaben im KDCS-Parameterbereich.

Funktion des Aufrufs	Einträge im KDCS-Parameterbereich
	KCOP	KCOM	KCLA	KCRN	KCUS
Schreiben in einen LSSB	"SPUT"	"DL"/ "MS"/"ES" (jeweils gleiche Wirkung)	Länge	Name des LSSB	-
Schreiben in einen GSSB	"SPUT"	"GB"	Länge	Name des GSSB	-
Schreiben in einen ULS	"SPUT"	"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, der die zu schreibende Nachricht enthält.

Versorgen der Parameter
Feldname im KDCS-Parameterbereich	Inhalt
KCOP	"SPUT"
KCOM	"GB"/"DL"/"MS"/"ES"/"US" ("DL", "MS" und "ES" haben jeweils die gleiche Wirkung)
KCLA	Länge in Byte
KCRN	Name des Bereichs
KCUS	Benutzerkennung/LSES-Name/Association-Name/Leerzeichen/-
Nachrichtenbereich
	Daten

KDCS-Aufruf
1. Parameter	2. Parameter
KDCS-Parameterbereich	Nachrichtenbereich

C/C++-Makroaufrufe
Makronamen	Parameter
KDCS_SPUTGB/KDCS_SPUTDL/KDCS_SPUTMS/KDCS_SPUTES	(nb,kcla,kcrn)
KDCS_SPUTUS	(nb,kcla,kcrn,kcus)

Rückgaben von openUTM
Feldname im KB-Rückgabebereich	Inhalt
KCRCCC	Returncode
KCRCDC	interner Returncode

In den KDCS-Parameterbereich tragen Sie für den SPUT-Aufruf ein:

KCOP

im Feld KCOP den Operationscode SPUT.

KCOM

im Feld KCOM die Angabe,

• ob in einen LSSB geschrieben werden soll ("DL" oder "MS" oder "ES") oder

• ob in einen GSSB geschrieben werden soll ("GB") oder

• ob in einen ULS-Block geschrieben werden soll ("US").

Die Einträge "MS" und "ES" haben bei openUTM die gleiche Wirkung wie "DL".

KCLA

im Feld KCLA die Länge der Daten, die Sie im Nachrichtenbereich zur Übergabe bereitstellen. Die Länge wird nicht in den LSSB/GSSB/ULS geschrieben.

KCRN

im Feld KCRN den Namen des LSSB/GSSB oder ULS-Blocks, der angelegt werden soll bzw. in den die Daten geschrieben werden sollen. Leerzeichen und binär null sind ungültige Einträge.

KCUS

im Feld KCUS die Benutzerkennung/LSES-Name/Association-Name (bei KCOM=US), wenn ein ULS-Block einer fremden Benutzerkennung/Session/Association beschrieben werden soll, sonst Leerzeichen. Wird eine fremde Benutzerkennung/LSES-Name/Association-Name in KCUS eingetragen, dann muss die eigene Benutzerkennung administrationsberechtigt sein.

Bei KCOM = DL/MS/ES/GB: irrelevant.

Nachrichtenbereich

Im Nachrichtenbereich tragen Sie die Nachricht ein, die Sie ausgeben wollen.

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, aus dem openUTM die Nachricht lesen 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:

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 SPUT-Aufruf

Im Programm sind auswertbar:

000	Die Operation wurde ausgeführt.
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 gegeben, obwohl dies in der Generierung nicht erlaubt wurde. bei KCOM=US: der Aufruf wurde im ersten Teil des Anmelde-Vorgangs oder 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	Der Name in KCRN ist 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.

Die folgende Tabelle beschreibt, wie die Aufruffolge SPUT . . . RSET oder SPUT . . . PEND/PGWT auf GSSBs, ULSs und LSSBs wirkt

Aufruf		Wirkung auf GSSBs/ULSs	Wirkung auf LSSBs
SPUT		sperrt; falls noch nicht vorhanden, werden GSSBs erzeugt, vorhandene GSSBs werden ersetzt	erzeugt oder ersetzt
...	PEND KP PGWT KP/PR	lässt rücksetzbar und gesperrt	lässt rücksetzbar
...	PEND RE/SP PGWT CM	setzt gültig (sie sind nicht mehr rücksetzbar) und entsperrt (d.h. andere Transaktionen können sie verwenden)	setzt gültig; sie sind nicht mehr rücksetzbar
....	PEND FI/FC		löscht; sie sind nicht mehr verfügbar
....	RSET PEND RS PGWT RB	macht Änderungen rückgängig und entsperrt; ein GSSB wird gelöscht, wenn er in dieser Transaktion erzeugt wurde	macht Änderungen rückgängig
....	PEND ER/FR		löscht

Beachten Sie bitte folgende Eigenschaften von GSSBs, ULSs und LSSBs:

• Ein GSSB steht allen Teilprogrammen einer Anwendung zur Verfügung, d.h. er kann von allen Teilprogrammen überschrieben werden. Sie müssen durch entsprechende Namensvergabe dafür sorgen, dass er von anderen Teilprogrammen nicht unbeabsichtigt überschrieben werden kann.

• Unix-, Linux- und Windows-Systeme
  In UTM-Cluster-Anwendungen stehen GSSB und ULS Cluster-weit zur Verfügung. D.h. ein GSSB oder ULS, den Sie mit SPUT erzeugen/schreiben, existiert in jeder Knoten-Anwendungen und kann dort mit SGET gelesen werden.

• Ein LSSB ist einem Vorgang eindeutig zugeordnet.

• Ein GSSB, LSSB oder ULS-Block hat immer die Länge des zuletzt aufgerufenen SPUT. Sie können maximal 32767 Bytes lang sein.

• Der Name eines ULS-Blocks wird bei der Generierung definiert (wie ein TLS-Block).

• Die maximale Anzahl der GSSBs bzw. LSSBs wird bei der Generierung festgelegt.

Eigenschaften des SPUT-Aufrufs

• Der SPUT-Aufruf für einen GSSB/ULS sperrt diesen GSSB bzw. ULS-Block bis zum Ende der Transaktion d.h. bis PEND RE, SP, FI, FC, RS oder ER/FR.

  Ein GSSB/ULS-Block bleibt nach einem SPUT-Aufruf bei einem nachfolgenden PEND KP bzw. PGWT KP-Aufruf oder einem PEND PA/PR bzw. PGWT PR (beim Warten auf eine DGET-Nachricht) über das Ende des Verarbeitungs-/Dialog-Schrittes hinweg von dieser Transaktion gesperrt.
  Eine andere Transaktion, die diesen GSSB/ULS-Block mit SGET, SPUT oder SREL bearbeiten will, wird zurückgewiesen bei:

  • PEND KP und PGWT KP

  • PEND PA/PR mit Taskwechsel wegen TAC-Klassensteuerung

  • PEND PA/PR oder PGWT PR mit Warten auf eine DGET-Nachricht.

  Bei Transaktionsende oder Rücksetzoperationen werden alle gesperrten GSSBs und ULS-Blöcke freigegeben.

  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.

• GSSBs mit Länge 0 in KCLA sind zulässig. Über einen solchen GSSB können sich Anwendungsprogramme verständigen, wobei nur ausgewertet wird, ob der GSSB gesperrt ist oder nicht. Einen GSSB mit der Länge 0 löscht openUTM jedoch beim nächsten Start der Anwendung. Auch KDCUPD überträgt GSSBs der Länge 0 nicht in eine neue KDCFILE (siehe openUTM-Handbuch „Anwendungen generieren“, KDCFILE ändern).

• Ein SPUT-Aufruf mit KCLA=0 kann auch dazu verwendet werden, um den Inhalt von ULS-Blöcken zu löschen.