KC_LOCK_MGMT - Release locks in UTM cluster applications

On Unix, Linux and Windows Systems only.

You can use KC_LOCK_MGMT to:

• Sign off all users or an individual user who are/is signed on at an abnormally terminated node application (KDCOFF). Any service data for this user that is valid globally in the cluster is lost when you do this.

  For this function, you use the sub-opcodes KC_SIGNOFF_ALL and KC_SIGNOFF_SINGLE.

• For all users or an individual user who have/has a service bound to a terminated node application, you can mark this service for abnormal termination and this way make it possible for the users or user to sign on again at another node application. The bound service is terminated abnormally the next time the node application to which it is bound is started.

  For this function, you use the sub-opcodes KC_ABORT_BOUND_SERVICE, KC_ABORT_ALL_BOUND_SERVICES and KC_ABORT_PTC_SERVICE.

• Release a cluster user file lock set on an abnormally terminated KDCDEF run (subopcode KC_UNLOCK_USF).

Period of validity / transaction management /clusters

The call permanently modifies the cluster user file. The modification takes effect immediately and cannot be undone by rolling back the transaction.

This function is only available for UTM cluster applications.

Parameter settings
Parameter area
Field name	Contents
version	KC_ADMI_VERSION_1
retcode	KC_RC_NIL
version_data	KC_VERSION_DATA_11
opcode	KC_LOCK_MGMT
subopcode1	KC_ABORT_ALL_BOUND_SERVICES / KC_ABORT_BOUND_SERVICE / KC_ABORT_PTC_SERVICE / KC_SIGNOFF_ALL / KC_SIGNOFF_SINGLE / KC_UNLOCK_USF
id_lth	0
select_lth	0
data_lth	Length of the data structure / 0
Identification area
—
Selection area
—
Data area
Data structure / 0

KDCADMI-Aufruf

KDCADMI (&parameter_area, NULL, NULL, &data_area)

Data returned by UTM
Parameter area
Field name	Content
retcode	Return codes

subopcode1

In subopcode1, you specify the action that openUTM is to perform. You can specify the following subcodes:

KC_ABORT_ALL_BOUND_SERVICES

Marks all the services that are bound to a terminated node application for abnormal termination. This allows the corresponding users to sign on at other node applications (KDCSIGN). The bound services are terminated abnormally the next time the node application to which they are bound is started.

KC_ABORT_BOUND_SERVICE

Marks a user service that is bound to a terminated node application for abnormal termination. This allows the user to sign on at another node application (KDCSIGN). The bound service is terminated abnormally the next time the node application to which it is bound is started.

KC_ABORT_PTC_SERVICE

Marks a user service that is bound to a terminated node application and has a transaction in PTC state for abnormal termination. This allows the user to sign on at another node application (KDCSIGN). The bound service is terminated abnormally the next time the node application to which it is bound is started.

KC_SIGNOFF_ALL

Sign off all users who are signed on at an abnormally terminated node application so that these users can sign on at another node application. Service data that is valid throughout the cluster for these users is lost.

KC_SIGNOFF_SINGLE

Sign off a single user who is signed on at an abnormally terminated node application so that this user can sign on at another node application. Service data that is valid throughout the cluster for this user is lost

KC_UNLOCK_USF

Releases the lock in the cluster user file after a KDCDEF run was terminated abnormally. It is only necessary to issue the call with subopcode KC_UNLOCK_USF if a KDCDEF has terminated abnormally and a subsequent KDCDEF run outputs message K516 with error code 8.

data_lth

In data_lth, enter the length of the data structure in the data area or 0.

Data area

In the data area, you must specify the data structure kc_lock_mgmt_str for all subopcode1 values excluding KC_UNLOCK_USF:

The data structure kc_lock_mgmt_str is defined as follows:

struct kc_lock_mgmt_str

char mg_name[8];

char mg_node[4];

The fields in the data structure have the following meanings:

mg_name

• • • • • Only for subopcode1=KC_SIGNOFF_SINGLE:
          Name of the user who is to be signed off.

        • If subopcode1=KC_ABORT_BOUND_SERVICE:
          Name of the user with service which is bound to a terminated node application and is to be marked for abnormal termination.

        • If subopcode1=KC_ABORT_PTC_SERVICE:
          Name of the user with a service in the PTC state which is bound to a terminated node application and is to be marked for abnormal termination.

        • Other values for subopcode1: irrelevant
          You do not need to specify the node number. openUTM identifies this.

mg_node

• Only for subopcode1=KC_SIGNOFF_ALL:
  Number of the node from which all the users are to be signed off.

• If subopcode1=KC_ABORT_ALL_BOUND_SERVICES:

• Number of the node that was terminated. All the service bound to this node should be marked for abnormal termination.

• Other values for subopcode1: irrelevant

retcode

openUTM indicates the return code from the call in the retcode field. Alongside the return codes listed in section "Return codes", the following return codes may also occur:

Maincode = KC_MC_REJECTED

The call was rejected by UTM.

Subcodes:

KC_SC_CUSF_TRANSIENT_ERROR (only on BS2000 systems)

For each subopcode1:
Temporary error when accessing the cluster user file; please repeat the call.

KC_SC_CUSF_RT_CODE_NOT_OK

For each subopcode1: Internal UTM error.
Please contact system support.

KC_SC_CUSF_INVALID_STATE

For subopcode1= KC_SIGNOFF_ALL/KC_ABORT_ALL_BOUND_SERVICES:
The specified node application has never been started or is currently running. The call can only be executed in the node statuses FAIL or ABTERM.
For subopcode1= KC_SIGNOFF_SINGLE:
The node application at which the specified user is signed in is currently running.
If subopcode1= KC_ABORT_BOUND_SERVICE/KC_ABORT_PTC_SERVICE:
The node application to which the service of the specified user is bound is currently running.

KC_SC_CUSF_USER_HAS_NO_BND_SRV

For subopcode1=KC_ABORT_BOUND_SERVICE: The user has no bound service.

KC_SC_CUSF_USER_HAS_NO_PTC

For subopcode1=KC_ABORT_PTC_SERVICE: The user has no node-bound service with a transaction in the PTC state.

KC_SC_CUSF_USER_HAS_PTC

For subopcode1=KC_ABORT_BOUND_SERVICE: The user has a node-bound service with a transaction in the PTC state.

KC_SC_CUSF_USER_NOT_FOUND

For subopcode1=KC_SIGNOFF_SINGLE/KC_ABORT_BOUND_SERVICE/KC_ABORT_PTC_SERVICE: The user was not found.

KC_SC_CUSF_USER_NOT_SIGNED

For subopcode1=KC_SIGNOFF_SINGLE: The user is not signed in at any node.

KC_SC_DATA_MISSING

mg_name is not binary zero and subopcode1=KC_SIGNOFF_ALL, KC_ABORT_BOUND_SERVICE or KC_ABORT_ALL_BOUND_SERVICES.

KC_SC_NOT_NULL

mg_node is not binary zero and subopcode1=KC_SIGNOFF_SINGLE, KC_ABORT_BOUND_SERVICE or KC_ABORT_PTC_SERVICE.