KC_CHANGE_APPLICATION- Exchange application program

You can initiate the exchange of the entire application program during the application run using KC_CHANGE_APPLICATION. In this way, you can exchange program units and add new program units to the application program without having to terminate the application. See the openUTM manual “Using UTM Applications” for more information on exchanging programs.

You can carry out the following operations using KC_CHANGE_APPLICATION:

• Terminate a UTM application on a BS2000 system that was generated with load modules in all processes and reload it.

  You will need this function to exchange load modules in a common memory pool. During a reloading, the current version of the load module i loaded that has been previously specified with a KC_MODIFY_OBJECT call for the object type KC_LOAD_MODULE.

  In addition, termination of the application program in all processes and a subsequent reload will unload all load modules generated with the load mode set to ONCALL.

  Only subopcode1=KC_NEW and KC_SAME are possible. KC_SAME has the same effect as KC_NEW

• An entire UTM application program on Unix, Linux or Windows systems can be exchanged (subopcode1=KC_NEW) by the application program of the next highest file generation in the file generation directory filebase/PROG (filebase= base name of the application).

  You can also undo program exchange using KC_CHANGE_APPLICATION, meaning you can switch back to the previously loaded application program (subopcode1=KC_OLD) or you can reload the application program (subopcode1=KC_SAME) without switching to another file generation.

The following requirements must be met:

• For UTM applications on a BS2000 system generated with load modules, you need to mark the parts of the application that are in a common memory pool and are to be exchanged beforehand using KC_MODIFY_OBJECT calls and the KC_LOAD_MODULE object type (see "obj_type=KC_LOAD_MODULE").

• When exchanging a UTM application program on Unix, Linux or Windows systems, the different versions of the application program (including the version currently loaded) should be administered using the UTM tool KDCPROG in the file generation directory filebase/PROG. The file generation directory must have been created using KDCPROG (KDCPROG CREATE).

  If the file generation directory filebase/PROG does not exist, UTM will reload the application program filebase/utmwork (on Unix or Linux systems) or filebase\utmwork (on Windows systems).

The program exchange is described in the openUTM manual “Using UTM Applications”.

The following points should be noted when exchanging the application program:

• The program units added to the new application program must have been defined at the time of the KDCDEF generation or they must have been dynamically configured by means of administration functions.

• No previously existing program units may be missing in the new application program. Jobs accepted for a transaction code for which no program unit exists after program exchange will be terminated abnormally (PEND ER) by UTM during execution. 

Procedure / period of validity / transaction logging / cluster:

The call initiates program exchange, meaning that a job is created to exchange the programs. The exchange itself will not have been completed when control is returned to the program unit. Program exchange is not subject to transaction logging - it cannot be undone in the same transaction by following it up with a RSET call.

Each process in the application program is exchanged individually. This is done by terminating the application program running for this process and then loading the new application program. The application program is only exchanged for one process at a time in order to avoid having to interrupt operations to implement program exchange. While the application program is being exchanged for a given process, jobs from other processes are also being processed concurrently. These jobs may then contain processes in which the old application program is still running. This leads to a situation where jobs are processed by both the old and the new application programs during the exchange phase.

The following applies in UTM cluster applications (Unix, Linux and Windows systems):
The call applies globally to the cluster, i.e. the application exchange is initiated in every running node application.

After the job has been processed, UTM sends you a UTM message informing you of the success or failure of the program exchange procedure. UTM sends the UTM message K074 if program exchange was carried out successfully. If UTM could not execute the program exchange, then it sends UTM message K075. If an error occurred, then UTM message K078 is sent in addition to K074 or 075. UTM message K078 contains the cause of the error as an insert.

KDCAPPL ("KDCAPPL - Change properties and limit values for an operation"), PROG operand

Data to be supplied

Function of the call	Data to be entered in the
	parameter area 1	identification area	selection area	data area
In UTM application on Unix, Linux and Windows systems with Shared Objects/ DLLs: Exchange the current application program with the next highest version of the application program	subopcode1: KC_NEW	——	——	—— (A pointer to a data area to which UTM can return data must be passed in the call.)
In UTM application on Unix, Linux and Windows systems with Shared Objects/ DLLs: Undo program exchange, i.e. exchange the current application program with the next lowest version of the application program	subopcode1: KC_OLD	——	——
In UTM applications on Unix, Linux and Windows systems with Shared Objects/DLLs: Reload application program from the same file generation.	subopcode1: KC_SAME	——	——
In UTM applications on BS2000 systems with load modules: Terminate the application program in all processes and then restart it in order to exchange parts of the application in the common memory pool. Static application parts can therefore also be exchanged when the application is linked before.	subopcode1: KC_NEW / KC_SAME	——	——	——

¹ The operation code KC_CHANGE_APPLICATION 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_CHANGE_APPLICATION
subopcode1	KC_NEW  /  KC_SAME / KC_OLD (Unix, Linux and Windows systems)
id_lth	0
select_lth	0
data_lth	Length of the data area / 0
Identification area
—
Selection area
—
Data area
—

KDCADMI call

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

Data returned by UTM
Parameter area
Field name	Contents
retcode	Return codes
data_lth_ret	Actual length of the data in the data area
Data area
Data structure kc_change_application_str / —

subopcode1

You can use subopcode1 to set which type of program exchange is to be executed. The following types of exchanges can be carried out:

KC_NEW	When exchanging a UTM application on a Unix, a Linux or a Windows system, UTM loads the application program from the next highest file generation. For a UTM application on a BS2000 system generated with load modules, UTM terminates the application program successively in all processes and reloads it again immediately. The current version of each of the load modules is loaded, meaning that the load modules in the common memory pool marked in KC_MODIFY_OBJECT calls are exchanged. Static application parts can therefore also be exchanged when the application is linked before.
KC_OLD	When exchanging a UTM application on Unix, Linux or Windows systems, UTM loads the application program from the next lowest file generation. In this way, the old application program can be reloaded if errors are detected in the application program after switching to a new file generation.
KC_SAME	On Unix, Linux and Windows systems, openUTM loads the application program from the same file generation. On BS2000 systems, KC_SAME has the same effect as KC_NEW.

data_lth

in the data_lth field you specify the length of the data area provided to contain the data returned by UTM.

When exchanging a UTM application on Unix, Linux or Windows systems, you must specify data_lth >= sizeof (kc_change_application_str).

You must pass a pointer to the data area in the function call.

When exchanging a UTM application program under a BS000 system generated with load modules, you must set data_lth=0. UTM does not return any data. 

retcode

in the retcode field UTM stores the return code of the call. In addition to the return codes listed in section "Return codes", the following codes can also be returned when the application program has been exchanged:

Main code = KC_MC_REJECTED

The call was rejected by UTM.

Subcodes:

KC_SC_NOT_CHANGEABLE

The application was started in the dialog. Program exchange is not possible.

KC_SC_FILE_ERROR (only on Unix, Linux and Windows systems)

An error occurred while accessing the file generation of the application program to be loaded. UTM produced UTM message K043 with the DMS return code.

KC_SC_NOT_GEN (only on BS2000 systems)

The UTM application is gererated without load modules.

KC_SC_NO_GLOB_CHANG_POSSIBLE

Only in UTM cluster applications:
No global administration changes are possible since the generation of the node applications is not consistent at present.

KC_SC_JFCT_RT_CODE_NOT_OK

Only for UTM cluster applications:
Internal UTM error
Please contact system support.

Main code = KC_MC_REJECTED_CURR

The call cannot be processed at the current time.

Subcode:

KC_SC_CHANGE_RUNNING

A program exchange is already being executed, meaning a program exchange started earlier is not yet complete.

KC_SC_INVDEF_RUNNING

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

Maincode = KC_MC_RECBUF_FULL

Subcode:

KC_SC_NO_INFO

Only for UTM cluster applications:
The buffer containing the restart data is full (see openUTM manual “Generating Applications”, KDCDEF control statement MAX, RECBUF parameter).

data_lth_ret

In the data_lth_ret field of the parameter area, UTM returns the actual length of the data in the data area.

Data area

When exchanging a UTM application on Unix, Linux or Windows systems, UTM returns the data structure kc_change_application_str to the data area if a pointer to a data area was passed in the KDCADMI call.

struct    kc_change_application_str

char program_fgg_new[4];

char program_fgg_old[4];

program_fgg_new

UTM returns the file generation number of the application program loaded as a result of program exchange.

program_fgg_old

UTM returns the file generation number of the application program loaded before program exchange was executed.