KC_DELETE_OBJECT allows you to delete objects belonging to one of the following object types from the configuration:
transport connections to remote LU6.1 applications (KC_CON)
key sets (KC_KSET)
LU6.1 sessions (KC_LSES)
transaction codes by means of which service programs can be started in partner applications (KC_LTAC)
LTERM partners used to connect clients and printers (KC_LTERM)
clients and printers (KC_PTERM)
application program units and VORGANG exits (KC_PROGRAM)
transaction codes and TAC queues (KC_TAC)
user IDs including their queues (KC_USER)
You can find more detailed information on dynamically deleting objects from the configuration in chapter "Changing the configuration dynamically".
Objects that you are not allowed to delete
LTERM partners that belong to an LTERM pool or multiplex connection
LTERM partners belonging to an LTERM group (group or primary LTERM) or to an LTERM bundle (master or slave LTERM)
printer control LTERMs
the LTERM partner KDCMSGLT that UTM creates internally for the MSGTAC service
program units that belong to the START, SHUT, FORMAT or INPUT event exits
program units and VORGANG exits that are statically linked into the application program
the KDCMSGTC, KDCSGNTC, KDCBADTC transaction codes of the event services
transaction codes assigned to a transport system access point (BCAMAPPL) as SIGNON-TAC
the dead letter queue KDCDLETQ
statically linked programs with event exits
the KDCSHUT administration command of the KDCADM administration program
the KDCTXCOM and KDCTXRLB transaction codes reserved for XATMI
the KDCMSGUS user ID that UTM creates internally for the MSGTAC service
a user ID assigned to a terminal for automatic KDSIGN or to a UPIC, APPLI or SOCKET client as a connection user ID
The following must be observed when deleting objects:
A program unit or a VORGANG exit may only be deleted after all the transaction codes belonging to them have been deleted.
An LTERM partner may only be deleted if no more clients or printers are assigned to it.
A user ID may only be deleted if there are no more users or clients signed on under this user ID, i.e.:
The user must not be signed on in a standalone application with
SIGNON MULTI-SIGNON=NO.In a standalone application with SIGNON MULTI-SIGNON=YES,
a user with RESTART=YES must not be signed on,
a user with RESTART=NO must not be signed on via a terminal connection.
In a UTM cluster application with SIGNON MULTI-SIGNON=NO,
no genuine user may be signed on,
a connection user must not be signed on at the node application at which the administration 'Delete' call is executed.
In a cluster application with SIGNON MULTI-SIGNON=YES,
no genuine user with RESTART=YES may be signed on,
a connection user must not be signed on at the node application at which the administration 'Delete' call is executed,
a user with RESTART=NO may not be signed on via a terminal connection at the node application at which the administration 'Delete' call is executed.
When a client/printer is deleted, it must not be connected to the application.
A logical connection for distributed processing by means of LU6.1 may not be deleted when it is not set up.
An LU6.1 session may only be deleted when it is not set up and is not in the P state (prepare to commit).
Effects of deletion during the application run
We distinguish two methods of deletion:
immediate delete (with subopcode1=KC_IMMEDIATE).
This method is only possible in conjunction with user IDs (KC_USER) and transport connections to LU6.1 applications (KC_CON). The immediate deletion of a user ID or a CON object causes the space in the object table to be freed up and made available for further use immediately. Immediate deletion is only possible for users IDs (KC_USER) and transport connections to LU6.1 applications (KC_CON). You can generate a new user ID using the same name after the deletion.
Immediate deletion is only possible in standalone UTM applications.delayed delete (with subopcode1=KC_DELAY)
Delayed deletion has the effect of a “permanent lock”. This process does not free up space in the object table.
The object’s name remains reserved, i.e. you cannot generate dynamically a new object using this name within the same name class.
The delayed deletion of transport connections to LU6.1 applications (KC_CON) is not possible in standalone UTM applications.In UTM cluster applications, only delayed deletion is possible.
In UTM cluster applications, it is possible to delete objects with an update generation without having to terminate the entire UTM cluster application. To implement this change in all the running node applications, it is necessary to terminate the individual node applications one after the other and then start them with the new generation.For details see openUTM manual “Using UTM Applications” subsection "Update generation in a cluster”.
The deletion of an object cannot be undone.
The inverse KDCDEF does not create KDCDEF control statements for deleted objects.
The effects of the deletion of an object on unprocessed asynchronous jobs, asynchronous messages, open dialog services etc. that relate to that object are described in chapter "Changing the configuration dynamically".
Procedure / period of validity / transaction management / cluster
The call is subject to transaction management. The object is deleted from the configuration only after the program unit run has ended (for PEND). The call can be rolled back with an RSET call that is executed in the same transaction.
The deletion remains effective even after the UTM-S- and UTM-F applications have terminated; it cannot be undone.
The following applies in UTM cluster applications (Unix, Linux and Windows systems):
The call applies globally to the cluster, i.e. objects are deleted from the configuration in all the node applications.
Data to be supplied
Function of the call | Data to be entered in the | |||
parameter area 1 | identification area | selection | data area | |
Delete transport connections to LU6.1 applications | subopcode1: | Name of the partner application, name of the computer, name of the local application | —— | —— |
Delete a key set | subopcode1: | Name of the key set | —— | —— |
Delete an LU6.1 session | subopcode1: | Local half-session name | —— | —— |
Delete a transaction code by means of which service programs are started in partner applications | subopcode1: | Name of the transaction code | —— | —— |
Delete an LTERM partner from the configuration | subopcode1: | Name of the LTERM partner | —— | —— |
Delete a client or printer from the configuration | subopcode1: | Name of the client/printer, computer name, BCAMAPPL name | —— | —— |
Delete a program unit from the configuration | subopcode1: | Program name | —— | —— |
Delete a transaction code or TAC queue from the configuration | subopcode1: | TAC name | —— | —— |
Delete a user ID including its queue from the configuration | subopcode1: | User ID | —— | —— |
1 The operation code KC_DELETE_OBJECT must be specified in the parameter area in all cases.
Parameter settings | |
Parameter area | |
Field name | Contents |
version | KC_ADMI_VERSION_1 |
retcode | KC_RC_NIL |
version_data | KC_VERSION_DATA_11 |
opcode | KC_DELETE_OBJECT |
KC_DELAY / KC_IMMEDIATE | |
Object type | |
1 | |
Length of the object name in the identification area | |
select_lth | 0 |
data_lth | 0 |
Object name | |
Selection area | |
— | |
Data area | |
— | |
KDCADMI call |
KDCADMI (¶meter_area, &identification_area, NULL, NULL) |
Data returned by UTM | |
Parameter area | |
Field name | Contents |
Return codes | |
subopcode1
In subopcode1 you specify the method of deletion.
KC_DELAY
if an object is to be marked as deleted, i.e. it is to be permanently locked (delayed delete).
KC_DELAY in obj_type=KC_CON is not permitted in standalone openUTM applications.
KC_IMMEDIATE
is only allowed in standalone openUTM applications with obj_type=KC_USER and obj_type=KC_CON.
You must specify KC_IMMEDIATE, if a user ID or LU6.1 connection is to be deleted immediately.
obj_type
In the obj_type field you must specify the type of object to be deleted.
You can specify the following object types:
KC_CON, KC_KSET, KC_LSES, KC_LTAC, KC_LTERM, KC_PROGRAM, KC_PTERM, KC_TAC (transaction code including TAC queue) and KC_USER (user ID including associated queue)
obj_number
Only one object can be deleted per call. For this reason, obj_number = 1 must be specified.
id_lth
In the id_lth field you must specify the length of the object name that you are passing in the identification area to UTM.
Identification area
In the identification area you must pass the name of the object to be deleted. The full name of the object must be specified. You must enter the following data:
for obj_type=KC_CON:
in the data structure kc_long_triple_str in the union kc_id_area; the name of the partner application, the name of the computer on which the application can be found and the name of the local application (BCAMAPPL name of the CON).
for obj_type=KC_KSET:
the name of the key set (kc_name8 in the union kc_id_area).
for obj_type=KC_LSES:
the name of the local half session (kc_name8 in the union kc_id_area).
for obj_type=KC_LTAC:
the name of the transaction code by means of which remote service programs are started (kc_name8 in the Union kc_id_area).
for obj_type=KC_PTERM:
in the data structure kc_long_triple_str in the union kc_id_area; the name of the client/printer, the name of the computer on which it can be found and the name of the local application (i.e. the BCAMAPPL name of the PTERM).
for obj_type=KC_PROGRAM:
the name of the program unit (kc_name32 in the union kc_id_area).
for obj_type=KC_TAC:
the name of the transaction code or the TAC queue (kc_name8 in the union kc_id_area).
for obj_type=KC_USER:
the name of the user ID (kc_name8 in the union kc_id_area).
retcode
In the retcode field UTM outputs the return codes of the call. In addition to the return codes listed in section "Return codes", the following codes can also be returned. Some of these return codes may arise independently of the object type specified; others only occur for certain object types.
Type-independent return codes:
Main code = KC_MC_REJECTED The call was rejected by UTM. Subcode: |
KC_SC_INVALID_OBJECT The object specified does not exist. |
KC_SC_DELETE_NOT_ALLOWED The object cannot be deleted, it has already been deleted or it has just been created (in the same transaction). |
KC_SC_JCTL_RT_CODE_NOT_OK Only in UTM cluster applications: |
KC_SC_NO_GLOB_CHANG_POSSIBLE Only in UTM cluster applications: |
KC_SC_GLOB_CRE_DEL_LOCKED Only in UTM cluster applications: |
Main code = KC_MC_REJECTED_CURR The call cannot be processed at the present time. Subcode: |
KC_SC_INVDEF_RUNNING An inverse KDCDEF is running, i.e. the job cannot be processed at the present time. |
Main code = KC_MC_RECBUF_FULL The buffer containing the restart information is full. (See the openUTM manual “Generating Applications”, KDCDEF control statement MAX, parameter RECBUF). Subcode: |
KC_SC_NO_INFO |
Return codes for obj_type = KC_CON:
Maincode = KC_MC_REJECTED The call was rejected by UTM. Subcodes: |
KC_SC_CONNECTED The specified LU6.1 connection cannot be deleted because it is currently set up. |
Maincode = KC_MC_PAR_INVALID An invalid value has been entered or a field has not been set in the parameter area. Subcode: |
KC_SC_SUBOPCODE1 Only in UTM cluster applications: |
Return codes for obj_type = KC_KSET:
Maincode = KC_MC_REJECTED The call was rejected by UTM. Subcodes: |
KC_SC_KSET_NOT_ADMINISTRABLE The KDCAPLKS key set cannot be deleted. |
Return codes for obj_type = KC_LSES:
Maincode = KC_MC_REJECTED The call was rejected by UTM. Subcodes: |
KC_SC_CONNECTED The LU6.1 session cannot be deleted because it is currently assigned to a connection. |
KC_SC_PTC_STATE The session has the transaction status P (prepare to commit). When it has this status it cannot be deleted. |
KC_SC_NOT_ALLOWED The session is currently occupied (not active). |
Return codes for obj_type = KC_LTERM:
Main code = KC_MC_REJECTED The call was rejected by UTM. Subcodes: |
KC_SC_LTERM_IS_MASTER The LTERM partner cannot be deleted because it is the master of an LTERM bundle. |
KC_SC_LT_DEL_GROUP_MASTER The LTERM partner cannot be deleted because it is the primary LTERM of an LTERM group. |
KC_SC_LT_DEL_SLAVE The LTERM partner cannot be deleted because it is the slave of an LTERM bundle. |
KC_SC_LT_DEL_ALIAS The LTERM partner cannot be deleted because it is the group LTERM of an LTERM group. |
KC_SC_REF_PTERM_NOT_DELETED The LTERM partner cannot be deleted because a client/printer assigned to the LTERM partner has not yet been deleted. |
KC_SC_LTERM_IS_CTERM The LTERM partner specified is a printer control LTERM. It cannot be deleted. |
KC_SC_OBJECT_TYPE_NOT_LTERM The object specified cannot be deleted because:
|
KC_SC_LTERM_NOT_ADMINISTRABLE The LTERM partner specified cannot be administered (for example, the LTERM partner KDCMSGLT which is created internally by UTM for the event service MSGTAC). |
Return codes for obj_type = KC_PROGRAM:
Main code = KC_MC_REJECTED The call was rejected by UTM. The object cannot be deleted. Subcodes: |
KC_SC_REF_TAC_NOT_DELETED A transaction code belonging to the program unit specified has not yet been deleted. |
KC_SC_PROGRAM_IS_STATIC The program unit cannot be deleted from the configuration because it belongs to a load module with load mode STATIC. |
KC_SC_PROGRAM_IS_USER_EXIT The object specified is an event exit that was statically configured with the KDCDEF control statement EXIT (START, SHUT, FORMAT or INPUT exit). |
Return codes for obj_type = KC_PTERM:
Main code = KC_MC_REJECTED The call was rejected by UTM. Subcodes: |
KC_SC_PTERM_CONNECTED The client/printer specified cannot be deleted because it is currently connected to the application. |
KC_SC_OBJECT_TYPE_NOT_PTERM The object specified cannot be deleted because:
|
Return codes for obj_type = KC_TAC:
Main code = KC_MC_REJECTED The call was rejected by UTM. Subcode: |
KC_SC_TAC_NOT_ADMINISTRABLE The transaction code or the queue specified cannot be administered (KDCMSGTC, KDCBADTC, KDCSGNTC, for example) or cannot be deleted (the transaction code KDCSHUT and the Dead Letter Queue). |
KC_SC_DELETE_NOT_ALLOWED The specified transaction code cannot be deleted (for example, a transaction code assigned to a transport access point as SIGNON-TAC) |
Return codes for obj_type = KC_USER (subopcode1 = KC_DELAY or KC_IMMEDIATE):
Main code = KC_MC_REJECTED The call was rejected by UTM. Subcodes: |
KC_SC_USER_CONNECTED A client/user with the user ID specified is currently signed on to the application. |
KC_SC_APPLICATION_WITHOUT_USER The application was generated without user IDs. |
KC_SC_USER_NOT_ADMINISTRABLE The user ID cannot be administered because it is, for example, the user ID KDCMSGUS that UTM creates internally for the MSGTAC event service. |
KC_SC_AUTO_SIGN_USER The user ID cannot be deleted, because it is assigned to an LTERM partner for automatic KDSIGN or as a connection user ID. |
obj_type = KC_USER and subopcode1 = KC_IMMEDIATE:
Main code = KC_MC_REJECTED The call was rejected by UTM. Subcodes: |
KC_SC_ASYN_SERVICE_RUNNING The user ID currently cannot be deleted because there is still an asynchronous service running under this user ID. |
KC_SC_CLIENT_SIGNED Immediate deletion of the user ID is currently not possible because a UPIC client, TS application or OSI TP partner is still signed on with this user ID. |
KC_SC_DEADLOCK Deadlock locking user-specific long-term storage (ULS) |
KC_SC_TIMEOUT Timeout locking user-specific long-term storage (ULS) |
KC_SC_OWNER_IN_TA User-specific long-term storage (ULS) cannot be locked because it is disabled by a transaction in which one of the KDCS calls PEND KP or PGWT KP was issued. |
KC_SC_PTC_STATE There is a transaction in the state PTC (prepare to commit) for the user ID. |
KC_SC_BOTTLENECK Services are stacked for the user ID, and a memory bottleneck has occurred. |
KC_SC_ALREADY_LOCKED The assigned ULS is locked by another transaction. |
KC_SC_NOT_ENOUGH_TASKS The UTM application does not currently have enough free processes to be able to wait for the lock of user-specific long-term storage (ULS) locked by a PTC transaction. Attempt to delete the user again later. |
Maincode = KC_MC_PAR_INVALID An invalid value has been entered or a field has not been set in the parameter area. Subcode: |
KC_SC_SUBOPCODE1 Only in UTM cluster applications: |