KC_SHUTDOWN - Terminate the application run

Using KC_SHUTDOWN you can terminate the current application run.

In UTM cluster applications (Unix, Linux and Windows systems), you can specify whether the application run is to be terminated at all nodes or only at the node at which the call is issued.

The following options are open to you:

• You can terminate the application run normally. UTM terminates the application run as soon as all running dialog steps have terminated (KC_NORMAL).

• You can schedule the application to terminate after a specified period (KC_WARN).

• You can terminate the application run once all the UTM-D dialogs have been terminated and all the UTM-D connections have been disconnected and at the latest, however, after a specified period (KC_GRACEFUL).

• You can abort the application run, i.e. immediately terminate (KC_KILL).

See also the openUTM manual “Using UTM Applications” for more information on terminating a UTM application run.

Please note the following when aborting the application:

Aborting the application (KC_KILL) cannot be handled as an asynchronous service: it is only permitted as a dialog. A call containing subopcode1=KC_KILL in an asynchronous service is rejected by UTM.

Please note the following when shutting down applications involving distributed processing:

You should preferably terminate applications with distributed processing with KC_GRACEFUL, alternatively with KC_WARN. When doing this, you should specify a time that is greater than the maximum period that a distributed transaction remains in the state PTC (i.e. transaction status P). This reduces the probability of distributed transactions still being in this state at the end of the application and of the application being terminated abnormally with ENDPET.

The following generally applies:
An application involving distributed processing is not terminated normally if, at the time of the abort operation, there are still services with transaction status P (’preliminary end of transaction’) or if confirmations have not yet been received for asynchronous messages to a partner server. UTM then outputs UTM message K060 stating ENDPET as the cause of the abort. No dumps are generated.

Execution / period of validity / transaction management / cluster

The KC_SHUTDOWN call is not subject to transaction management. It cannot be rolled back by an RSET call.

Aborting an application run (KC_KILL) takes immediate effect, there is no return to the program unit.

If the application is to be terminated (KC_NORMAL, KC_WARN and KC_GRACEFUL), the call originates a job, i.e. actions leading to shutdown are initiated.

The shutdown sequence, i.e. how and when UTM terminates the application run is determined by the value specified for subopcode1 in the parameter area. The shutdown sequence is described in section subopcode1.

The following applies in UTM cluster applications (Unix, Linux and Windows systems):
The effect of the call may be either global to the cluster or local to the node, i.e. the current application run may be terminated at all nodes or only at the node at which the call was issued.

KDCSHUT ("KDCSHUT - Terminate an application run")

Data to be supplied

Function of the call	Data to be entered in the
	parameter area 1	identification area	selection area	data area
Abort application run immediately (only as dialog)	subopcode1: KC_KILL	——	——	—— or kc_shutdown_str
Terminate application run normally	subopcode1: KC_NORMAL	——	——	—— or kc_shutdown_str
Terminate application run normally on expiry of a timer openUTM on a BS2000 system outputs a standard UTM message to all active users)	subopcode1: KC_WARN	——	——	kc_shutdown_str
Terminate application run on a BS2000 system normally after expiration of a message and send a UTM message to all active users	subopcode1: KC_WARN, subopcode2: KC_USER_MSG	——	——	kc_shutdown_str
Terminate the application run normally after all UTM-D connections have been cleared, and at the latest after the timer has expired.	subopcode1: KC_GRACEFUL	——	——	kc_shutdown_str

¹ The operation code KC_SHUTDOWN must always be specified in the parameter area.

Parameter settings
Parameter area
Field name	Content
version	KC_ADMI_VERSION_1
retcode	KC_RC_NIL
version_data	KC_VERSION_DATA_11
opcode	KC_SHUTDOWN
subopcode1	KC_GRACEFUL / KC_KILL / KC_NORMAL / KC_WARN
subopcode2	KC_USER_MSG / —
id_lth	0
select_lth	0
data_lth	Length of data in data area / 0
Identification area
—
Selection area
—
Data area
Data structure kc_shutdown_str / —

KDCADMI call

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

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

subopcode1
	Specify in subopcode1 how UTM is to terminate the application. You can choose from the following options:
	KC_GRACEFUL
		UTM prepares for the shutdown. The application is terminated as soon as all UTM-D dialogs have terminated and all UTM D connections have been disconnected or, at the latest, when the specified timer has expired. You must pass the value of the timer in the data area. The application is always terminated after the specified timer has expired. If there are no UTM-D connections, the application is immediately terminated normally.The following applies after the KC_GRACEFUL call has been processed: It is only possible for users with administration authorization to sign on. Signon attempts from other users will be rejected. It is only possible to call transaction codes for administration programs and the UTM user commands other than KDCOUT. No other services will be started by UTM. All active connections to LPAP and OSI-LPAP partners are set to QUIET.
	KC_KILL	The application run is aborted, i.e. it is terminated immediately. Open services are no longer terminated. A UTM dump is created for all processes stating REASON=ASIS99.
	KC_NORMAL
		The application run is terminated normally. Shutdown is initiated immediately. The following applies after the KC_SHUTDOWN call: Users/clients can no longer sign on to the application. No further jobs are accepted from partner servers. Users/clients which are already signed on cannot start any new services. New dialog inputs are no longer processed. If the new dialog input is part of a multi-step transaction, the multi-step transaction is rolled back to the last synchronization point. All logical connections to clients, printers and partner applications are shut down.Open services can be further processed after the next application start.
	KC_WARN
		UTM prepares for shutdown. The application is terminated once the specified timer has expired. You must pass the timer value in the data area. The following applies once the KC_SHUTDOWN call has been processed: Only users having administration privileges can sign on. Sign-on attempts by other users are rejected Only administration program transaction codes and UTM user commands other than KDCOUT can still be called. UTM will no longer start any other services. All active connections to LPAP and OSI-LPAP partners are set to QUIET.
subopcode2
	subopcode2 is only relevant if it specifies subopcode1=KC_WARN. In any other case, nothing may be specified in subopcode2. Specify subopcode2= KC_USER_MSG if UTM is to send a message to all currently active users in preparation for shutdown. You must pass the message which UTM is to send in the data area. The message is accepted in UTM applications on Unix, Linux and Windows systems, but no warning messages are output. If you do not specify subopcode2 with KC_WARN on BS2000, all active users are informed by a standard UTM message of the forthcoming shutdown and the time remaining until shutdown.
data_lth
	Specify in the data_lth field, the length of the data area which you are passing to UTM. for subopcode1=KC_KILL, KC_NORMAL: No data is passed to/from UTM in the data area (data_lth='0'), or the length of the data structure kc_shutdown_str which you pass in the data area. for subopcode1= KC_GRACEFUL, KC_WARN: Specify in the data_lth field the length of the data structure kc_shutdown_str which you are passing to UTM in the data area.
Data area
	For subopcode1=KC_WARN and subopcode1=KC_GRACEFUL, you must pass the data structure kc_shutdown_str to UTM in the data area. kc_shutdown_str must contain the size of the timer and, if subopcode2= KC_USER_MSG, the message to be sent as a warning to all terminal users. In the case of standalone UTM applications, values only need to be entered for KC_WARN and KC_GRACEFUL in the data area. The field scope in kc_shutdown_str is not evaluated. The following applies in UTM cluster applications: For each subopcode1: In the data structure kc_shutdown_str, you can use the scope field to control whether only the local node application is to be terminated or whether you want to terminate the entire UTM cluster application, i.e. all the node applications. If you want to initiate a global shutdown of the UTM cluster application, you must enter scope='G' in the data structure kc_shutdown_str . If you do not specify any data structure in the cluster then a local shutdown is performed.

The data structure kc_shutdown_str has the following structure:

struct kc_shutdown_str

char time_min[3];

char user_message[74];

char scope;

time_min	Specify in time_min the time in minutes after which UTM is to terminate the application run normally. You should specify a time that is greater than the maximum period that a distributed transaction remains in the state PTC (i.e. transaction status P). In job receiver services, this is the time generated with MAX PTCTIME and in LU6.1 job submitter services, it is the generated time time2 of the WAITTIME operand in the employed LTAC. Minimum value: '1' Maximum value: '255' The entry time_min='0' is rejected by UTM. If the application is to be terminated normally without any delay, you must specify subopcode1=KC_NORMAL. Features specific to UTM applications on BS2000 systems time_min is always output to active terminals together with the shutdown warning. In large UTM applications on BS2000 systems (configurations with many clients), UTM requires a certain amount of time to output the shutdown notice. The selected value of time_min should thus not be too small. In addition, you should define a sufficiently large value for cpu_time_msec (see kc_tac_str in chapter "kc_tac_str - Transaction codes of local services") for the transaction code by means of which the program unit is started with this KC_SHUTDOWN call. cpu_time_msec specifies the maximum CPU time which the program unit run may take up. If the time selected is too short, the shutdown may be aborted.
user_message
	Only relevant for subopcode2=KC_USER_MESSAGE. If no subopcode2 was specified, this area is ignored. Using user_message you can pass your own message which UTM is to send to all terminal users as a warning before shutdown. Maximum message length is 74 characters. openUTM on BS2000 systems If you do not pass your own warning message in user_message, UTM outputs UTM message K023 with the following inserts to all terminal users currently connected to the application: 'hour':'minutes':'seconds' APPLICATION 'name' WILL BE TERMINATED IN 'minutes' MINUTES openUTM on Unix, Linux and Windows systems No warning messages are output on Unix, Linux and Windows systems.
scope	Determines whether the local node application is terminated or the entire UTM cluster application, i.e. all the node applications. scope is only evaluated for UTM cluster applications.
	'L' 'G'	Only the local node application is terminated. All the node applications in the cluster and thereforealso the entire UTM cluster application are terminated.

retcode 

UTM writes the return codes for the call to the retcode field. In addition to the return codes listed in section "Return codes", the following codes may also occur:

Main code = KC_MC_REJECTED

The call was rejected by UTM.

Subcode:

KC_SC_NOT_ALLOWED

subopcode1 = KC_KILL has been used in an asynchronous service.

KC_SC_NO_GLOB_CHANG_POSSIBLE

The generation of the node applications is not currently consistent. You should first shut down the node applications with an old generation..

Main code = KC_MC_DATA_INVALID

A field in the data structure in the data area contains an invalid value.

Subcode:

KC_SC_INVALID_MOD

Only for subopcode1=KC_GRACEFUL and subopcode1=KC_WARN:
The application run was not terminated because the time specified in time_min is invalid.

Maincode = KC_MC_REJECTED_CURR

The call cannot be processed at present.

Subcode:

KC_SC_INVDEF_RUNNING

Only in UTM cluster applications:
An inverse KDCDEF is currently running, i.e. the job cannot be processed at present.

Maincode = KC_MC_RECBUF_FULL

Only in UTM cluster applications:

Subcode:

KC_SC_NO_INFO

The buffer containing the restart information is full (see openUTM manual “Generating Applications”, KDCDEF control statement MAX, parameter RECBUF).