You use the SGET (storage get) call to read data from a secondary storage area into a storage area of the program unit. The following may occur as secondary storage areas:
the global secondary storage area (GSSB)
the local secondary storage area (LSSB)
the user-specific long-term storage area (ULS)
If an LSSB is no longer required, it can be deleted at the same time by entering KCOM=RL. The contents of a ULS can only be deleted by writing (SPUT) with KCLA=0.
A GSSB must be deleted with a separate call (SREL); it remains locked until the end of the transaction or service. For further information, see the description of the SREL call.
A GSSB or ULS can be unlocked explicitly with the UNLK call.
Unix, Linux and Windows systems
In UTM cluster applications, GSSB or ULS areas are available throughout the cluster.
Setting the KDCS parameter area (1st parameter)
The table below shows the various options and the necessary entries in the KDCS parameter area.
Function of the call | Entries in the KDCS parameter area | ||||
|---|---|---|---|---|---|
KCOP | KCOM | KCLA | KCRN | KCUS | |
Read from LSSB | "SGET" | "KP" | Length | Name of the LSSB | — |
Read from LSSB and delete LSSB | "SGET" | "RL" | Length | Name of the LSSB | — |
Read from GSSB (and lock GSSB) | "SGET" | "GB" | Length | Name of the GSSB | — |
Read from ULS (and lock ULS) | "SGET" | "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 with binary zero.
Setting the 2nd parameter
Here you have to supply the address of the message area into which openUTM is to read the message.
Setting the parameters | |
Field name in the KDCS parameter area | Contents |
"SGET" | |
"KP"/"RL"/"GB"/"US" | |
Length in bytes | |
Name of the area | |
User ID / LSES name / association name / blanks | |
KDCS call | |
KDCS parameter area | Message area |
C/C++ macro calls | |
Parameters | |
KDCS_SGETKP/KDCS_SGETRL/KDCS_SGETGB | (nb,kcla,kcrn) |
KDCS_SGETUS | (nb,kcla,kcrn,kcus) |
openUTM return information | |
|---|---|
Contents | |
Data | |
Field name in the KB return area | |
Actual block length | |
Return code | |
Internal return code | |
For the SGET call you make the following entries in the KDCS parameter area:
KCOP
In the KCOP field, the SGET operation code.
KCOM
In the KCOM field:
KP (keep) to read from an LSSB - the area is retained
RL (release) to read from and delete an LSSB
GB to read from a GSSB
US to read a ULS block
KCLA
In the KCLA field, length of data to be transferred to the message area.
KCRN
In the KCRN field, name of the LSSB/GSSB or of the ULS block to be read from.
KCUS
In the KCUS field, user ID / LSES name / association name if a ULS block of a foreign user ID / LSES / association is to be read, otherwise blanks (if blanks are specified, the ULS block of the user / LSES / association who started the service is read).
If a foreign user ID / LSES / association is entered in KCUS, your own user ID / LSES / association must have administration privileges.
Irrelevant for KCOM = KP/RL/GB.
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 to which UTM 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:
Message area
the desired data in the specified message area.
KCRLM
in KCRLM, the actual length of the data in the LSSB/GSSB/ULS (in bytes). This enables you to detect deviations from the KCLA entry (important if specified KCLA value is smaller).
Exception: for KCLA = 0 UTM always returns KCRLM = 0.
KCRCCC
KCRCCC: the KDCS error 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 SGET call
The following codes can be analyzed in the program:
000 | Operation carried out. |
14Z | No area exists with the name specified in KCRN (only for KP, RL, GB). |
40Z | System cannot perform the operation (generation error or system error, deadlock, timeout); see KCRCDC. |
41Z | The call was issued in the first segment of the sign-on service although this is not allowed by the generation. For KCOM=US: The call wasis sued in the first segment of the sign-on service or in the sign-on service after a SIGN ON and before the PEND PS call. |
42Z | Entry in KCOM is invalid. |
43Z | Length entry in KCLA negative or invalid. |
44Z | Name in KCRN invalid. It is invalid if it consists solely of blanks or binary zero or has not been generated (in the case of ULS). |
46Z | Name 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. |
Features of the SGET call
The area is transferred in its actual length, but at the most in the length specified in KCLA. The actual length of the data in the GSSB, LSSB or ULS is returned in the KCRLM field.
If the length specified in KCLA is smaller than the actual length of the record to be read, the data is truncated at the right-hand side. You can capture this situation in a program unit (KCLA < KCRM).
If the length specified in KCLA is greater than the actual length of the record to be read (KCLA > KCRLM), the surplus part of the message area is undefined after the SGET call.
If an attempt is made in a program unit to perform an SGET read operation on a nonexistent storage area, the program unit will receive the error code 14Z ("No area with this name exists").
If SGET is used to access a GSSB or ULS, the following applies:
An SGET call for a GSSB or ULS locks the GSSB or ULS until the next synchronization point or rollback point, i.e. until PEND SP/RE/FI/FC/RS/ER/FR or RSET. If, following SGET, the processing step is terminated in a program unit with a PEND KP, PGWT KP, PGWT PR or with a PEND PA/PR call with a task change due to TAC class control or a wait for a DGET message, the access lock remains until the next synchronization point, unless the lock is cancelled beforehand with an UNLK call.
Reading from a non-existent GSSB has the same effect as creating a GSSB with simultaneous deletion (SPUT, SREL sequence).
The name of this GSSB remains locked until the next synchronization point or rollback point.
If the generated maximum number of GSSBs is already reached, the program unit receives the return code 40Z with KCRCDC K804.
Unix, Linux and Windows systems
In a UTM cluster application, reading from a non-existent GSSB requires four additional file accesses (to increment and decrement the GSSB counter). Consequently, in UTM cluster applications, it is advisable for performance reasons not to use any empty GSSBs but instead, for instance, a GSSB of length 1 for the serialization of program units, for example.
In 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.
When an SGET is used to access an LSSB, the following applies:
SGET KP causes the LSSB to remain available in the follow-up transaction of the service, i.e. after the subsequent PEND RE/SP.
SGET RL reads the LSSB and deletes it at the end of transaction (i.e. with PEND RE/SP/FI/FC/RS/ER/FR). Attempts to access in the meantime are rejected with 14Z.
You should always use this variant if the LSSB is no longer needed after reading in the current service.