You use the SPUT (storage put) call to write data from a specified area to a
global secondary storage area (GSSB) or a
local secondary storage area (LSSB) or a
user-specific long-term storage area (ULS).
Note that the name of a ULS block is defined at generation (ULS statement for KDCDEF), whereas you can select the names of GSSBs and LSSBs arbitrarily when you call SPUT.
Unix, Linux and Windows systems
In UTM cluster applications, GSSB or ULS areas are available throughout the cluster.
Setting the 1st parameter (KDCS parameter area)
The table below shows the various options and the necessary entries in the KDCS parameter area.
Function of the calls | Entries in the KDCS parameter area | ||||
|---|---|---|---|---|---|
KCOP | KCOM | KCLA | KCRN | KCUS | |
Write to LSSB | "SPUT" | "DL"/ "MS"/"ES" (all have same effect) | Length | Name of LSSB | — |
Write to GSSB | "SPUT" | "GB" | Length | Name of GSSB | — |
Write to ULS | "SPUT" | "US" | Length | Block name | User ID / LSES name/ association name/ blanks |
For KCOM = US all the fields not used in the KDCS parameter area are to be set to binary zero.
Setting the 2nd parameter
Here you have to supply the address of the message area which contains the message to be written.
Setting the parameters | |
Field name in the KDCS parameter area | Contents |
"SPUT" | |
"GB"/"DL"/"MS"/"ES"/"US" ("DL", "MS" and "ES" have the same effect) | |
Length in bytes | |
Name of the area | |
User ID / LSES name / association name / blanks | |
Data | |
KDCS call | |
KDCS parameter area | Message area |
C/C++ macro calls | |
Parameters | |
KDCS_SPUTGB/KDCS_SPUTDL/KDCS_SPUTMS/KDCS_SPUTES | (nb,kcla,kcrn) |
KDCS_SPUTUS | (nb,kcla,kcrn,kcus) |
openUTM return information | |
|---|---|
Field name in the KB return area | Contents |
Return code | |
Internal return code | |
For the SPUT call you make the following entries in the KDCS parameter area:
KCOP
In the KCOP field, the SPUT operation code.
KCOM
In the KCOM field, the entry indicating
whether writing should be to an LSSB ("DL" or "MS" or "ES"), or
whether writing should be to a GSSB ("GB"), or
whether writing should be to a ULS block ("US").
The entries "MS" and "ES" have the same effect as "DL" for openUTM.
KCLA
In the KCLA field, the length of the data which you make available in the message area. The length is not written to the LSSB/GSSB/ULS.
KCRN
In the KCRN field, the name of the LSSB/GSSB or ULS block to be initialized or to which the data is to be written. Blanks and binary zero are invalid entries.
KCUS
In the KCUS field, the user ID / LSES name / association name (for KCOM = US), if a ULS block of a foreign user ID / session / association is to be written, otherwise blanks. If you enter a foreign user ID / LSES name / association name in KCUS, your own user ID must have administration privileges.
For KCOM = DL/MS/ES/GB: irrelevant.
Message area
In the message area you have to enter the message which you want to output.
You specify the following for the KDCS call:
1st parameter
The address of the KDCS parameter area.
2nd parameter
The address of the message area from which openUTM is to read the message. You enter the address of the message area even if you have entered the length 0 in KCLA.
Macro names
The use of C/C++ calls is described in detail in the section "C/C++ macro interface".
openUTM returns:
KCRCCC
in the KCRCCC field: the KDCS return code, see next page.
KCRCDC
in the KCRCDC field: the internal return code of openUTM (see the openUTM manual ”Messages, Debugging and Diagnostics”).
KDCS return codes in the KCRCCC field for the SPUT call
The following codes can be analyzed in the program:
000 | Operation carried out. |
40Z | System cannot perform the operation (generation error or system error, deadlock, timeout), see KCRCDC. |
41Z | Call issued in the first segment of the sign-on service, although this is not allowed by the generation. For KCOM=US: the call was issued in the first segment of the sign-on service or after a SIGN ON and before the PEND PS call. |
42Z | Entry in KCOM is invalid. |
43Z | Length entry in KCLA is negative or invalid. |
44Z | Name in KCRN invalid if it consists solely of blanks or binary zero or has not been generated (in the case of ULS). |
46Z | Entry in KCUS is invalid. |
47Z | Message area missing or cannot be accessed in the specified length. |
49Z | Contents of fields not used in the KDCS parameter area not equal to binary zero (only for KCOM = US). |
An additional error code can be found in the dump:
71Z | INIT missing in this program |
The following table describes the effect of the call sequences SPUT ... RSET and SPUT ... PEND/PGWT on GSSBs, ULSs and LSSBs.
Call | Effect on GSSBs/ULSs | Effect on LSSBs | |
|---|---|---|---|
SPUT | locks: GSSBs are created if not already present, existing GSSBs are replaced | creates or replaces | |
... | PEND KP | leaves resettable and locked | leaves resettable |
... | PEND RE/SP/ | sets valid (they are then no longer resettable) and unlocks (i.e. other transactions can use them) | sets valid (they are then no longer resettable) |
... | PEND FI/FC | deletes (they are no longer available) | |
... | RSET/ | cancels changes and unlocks; a GSSB is deleted if created in this transaction | cancels changes |
... | PEND ER/FR | deletes | |
Please note the following features of GSSBs, ULSs and LSSBs:
A GSSB is available to all program units in an application, i.e. it can be overwritten by all program units. To avoid unintentional overwriting of GSSBs by other program units, you must ensure that their names are unique.
Unix, Linux and Windows systems
In UTM cluster applications, GSSB and ULS areas are available throughout the cluster. I.e. any GSSB or ULS that you create/write with SPUT exists in all node applications where it can be read using SGET.An LSSB is assigned uniquely to a service.
GSSBs, LSSBs and ULS blocks always take the length of the last SPUT called. This length cannot exceed 32767 bytes.
The name of a ULS block is defined at generation (as a TLS block).
The maximum number of GSSBs or LSSBs is defined at generation
Features of the SPUT call
The SPUT call for a GSSB/ULS locks this GSSB or ULS block until the end of the transaction, i.e. until PEND RE, SP, FI, FC, RS or ER/FR.
Following an SPUT call, a GSSB/ULS block remains locked by this transaction; a subsequent PEND KP or PGWT KP call or a PEND PA/PR or PGWT PR (in the case of a wait for a DGET message) retains the lock beyond the end of the processing/dialog step.
Another transaction that wants to process this GSSB/ULS block with SGET, SPUT or SREL will be rejected in the following cases.PEND KP and PGWT KP
PEND PA/PR with a task change due to TAC class control
PEND PA/PR or PGWT PR with waiting for a DGET message
At the end of a transaction or when there is a rollback operation, all locked GSSBs and ULS blocks are released.
In the section "Action with locked storage areas (TLS, ULS and GSSB)" there is a description of how openUTM reacts when the desired GSSB or ULS block is locked.
GSSB areas are permitted with length 0 in KCLA. These GSSBs can be used for communication between application programs; all that is evaluated is whether the GSSB is locked or not. However, openUTM deletes a GSSB with length 0 the next time the application is started. KDCUPD likewise does not transfer GSSBs with length 0 to a new KDCFILE (see the openUTM manual “Generating Applications”, changing KDCFILE).
You can also use a SPUT call with KCLA=0 to delete the contents of ULS blocks.