You use the UNLK (unlock) call to unlock one of the following storage areas:
the global secondary storage area (GSSB).
a block of the terminal-specific long-term storage area (TLS).
a block of the user-specific long-term storage area (ULS).
The area is not unlocked unless it was only read in the current transaction
Unix, Linux and Windows systems
In UTM cluster applications, GSSB and ULS areas are valid throughout the cluster. As a result, unlocking a GSSB or ULS with UNLK is effective 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 call | Entries in the KDCS parameter area | |||
|---|---|---|---|---|
KCOP | KCOM | KCRN | KCLT or KCUS | |
Unlock TLS (in dialog programs) | "UNLK" | "DA" | Block name | — |
Unlock TLS (in asynchronous programs) | "UNLK" | "DA" | Block name | LTERM name / LPAP name / OSI- LPAP name / Master-LPAP name |
Unlock GSSB | "UNLK" | "GB" | Name of GSSB | — |
Unlock ULS | "UNLK" | "US" | 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 parameters | |
Field name in the KDCS parameter area | Contents |
"UNLK" | |
"GB"/"DA"/"US" | |
Name of the area/block name | |
LTERM name / LPAP name / OSI- LPAP name / Master-LPAP name or | |
KDCS call | |
2nd parameter | |
KDCS parameter area | Message area |
C/C++ macro calls | |
Parameters | |
KDCS_UNLKGB | (kcrn) |
KDCS_UNLKDA | (kcrn,kclt) |
KDCS_UNLKUS | (kcrn,kcus) |
openUTM return information | |
|---|---|
Field name in the KB return area | Contents |
Return code | |
Internal return code | |
For the UNLK call you make the following entries in the KDCS parameter area:
KCOP
In the KCOP field, UNLK operation code.
KCOM
In the KCOM field, the type of storage to be unlocked:
GB for a global secondary storage area (GSSB).
DA for terminal-specific long-term storage area (TLS).
US for a user-specific long-term storage area (ULS).
KCRN
In the KCRN field, the name of the storage area to be unlocked.
KCLT
KCUS
Depending on the type of storage:
for unlocking a TLS in an asynchronous program: in the KCLT field, the name of the LTERM or (OSI) LPAP partner, whose TLS is to be unlocked.
for unlocking a TLS in a dialog program: irrelevant, the corresponding block of the associated TLS is always accessed.
for unlocking a ULS block: in the KCUS field, the user ID if a ULS block of a foreign user ID is to be unlocked or blanks for a ULS block of your own user ID. If you enter a foreign user ID in KCUS, your own user ID must have administration privileges.
If you want to unlock a ULS block of a remote session/association, you have to specify its name.
for unlocking a GSSB: irrelevant.
You specify the following for the KDCS call:
1st parameter
The address of the KDCS parameter area.
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.
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 UNLK call
The following codes can be analyzed in the program:
000 | Operation carried out. |
14Z | No GSSB/TLS exists with the name specified in KCRN. |
16Z | GSSB/TLS/ULS not locked by your own transaction or GSSB created or changed in same transaction or TLS changed in same transaction. |
40Z | System cannot perform the operation (generation error or system error, deadlock, timeout). |
42Z | Entry in KCOM is invalid. |
44Z | For GSSB: entry in KCRN is invalid (blanks or binary zero). For TLS and ULS: name of the block in KCRN is unknown or invalid. |
46Z | LTERM or LPAP partner in KCLT is invalid (only for asynchronous programs and TLS) or the user ID is unknown (only for ULS). |
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 UNLK call
An UNLK call to a TLS/ULS/GSSB is only useful after a read call (GTDA or SGET). If the area is changed in the current transaction with PTDA, SPUT or SREL (with GSSBs), openUTM rejects the call with KCRCCC = 16Z; the area remains locked until the end of transaction.
An UNLK call is useful, for example, before entering PEND KP or PGWT KP/PR. This causes TLS/ULS blocks and GSSBs to be released prior to the next synchronization point. This makes them available to the other transactions.
An UNLK call for an area not locked by your own transaction is rejected (return code 16Z).
Unix, Linux and Windows systems
In UTM cluster applications, an UNLK call unlocks a GSSB or ULS throughout the cluster, i.e. as soon as the UNLK call takes effect, transactions in other node applications are again able to access the unlocked area.