obj_type=KC_LOAD_MODULE

This operation relates to a load module (BS2000) or to a shared object or DLL (Unix, Linux and Windows systems).

You must pass the name of the load module/shared object to UTM in the identification area (field kc_name32 of union kc_id_area).

You must pass the data structure kc_load_module_str in the data area.

Possible modification

You can exchange a load module, a shared object or a DLL in an application program or mark a load module in the common memory pool (BS2000 systems) for exchange.

The specified load module/shared object/DLL must exist in the application configuration, i.e. it must have been statically generated with KDCDEF.

Specify the following in the data structure kc_load_module_str:

Field name	Meaning
version[24]	Pass in version the version of the load module or shared object to be loaded.
	The following only applies to BS2000 systems: In UTM applications on BS2000 systems, you must always specify the version of the load module to be loaded. For load modules which are generated with LOAD-MODE=STARTUP the version number of the old and the new load module may match. For load modules which are generated with LOAD-MODE=ONCALL or which are located completely or partially in a common memory pool the new version number must differ from the old version number. You can also specify *HIGHEST-EXISTING as the version. UTM then determines the highest version available in the library and loads it. In this case, after a successful call, UTM returns the highest element version determined in the version field. If a load module is generated with LOAD-MODE=POOL, (POOL,STARTUP) or (POOL,ONCALL) and with the version *HIGHEST-EXISITING, for version only *HIGHEST-EXISTING can be specified. This kind of module can only be reloaded by an application exchange; the highest available version is always loaded for a module generated in this way. If the string *UPPER-LIMIT is specified in the version field, UTM replaces this value with "@” in the output. When the exchange is initiated, the library assigned to the load module during KDCDEF generation (see also lib in kc_load_module_str, "kc_load_module_str - Load modules (BS2000 systems) or shared objects/DLLs (Unix, Linux and Windows systems)"), an element with the name specified in the identification area and the version specified in version must all be available. In UTM cluster applications, this applies for all node applications. If this kind of load module is not available in the program library, the administration call is rejected and the load module previously loaded remains loaded. In addition, the message K234 is output. You cannot replace load modules that have the STATIC load mode (load_mode='S'). Neither can load modules with the STARTUP load mode (load_mode='U') and which contain TCB entries be replaced.
	In UTM applications on Unix, Linux or Windows systems, you must specify the version if the shared object/DLL is generated with ONCALL load mode (load_mode='O'). In the case of shared objects/DLLs with STARTUP load mode (load_mode='U'), specifying the version is optional if you are not using the version concept.

Period of validity/ transaction management: type GID ("KC_MODIFY_OBJECT - Modify object properties and application parameters")

How exchange is made is determined by the load mode of the load module/shared object/DLL (field load_mode in kc_load_module_str, see "kc_load_module_str - Load modules (BS2000 systems) or shared objects/DLLs (Unix, Linux and Windows systems)"):

• load_mode='U' (STARTUP)

  The exchange is executed for each process before the next job is processed, without the current application program being terminated. Several application processes can be replaced simultaneously. You cannot initiate any further exchanges until program exchange has been completed by all application processes.

• load_mode='O' (ONCALL)

  The exchange is performed for each process only when a program unit from this load module/shared object/DLL is next called in this process. Exchange can be performed simultaneously be several processes.

• load_mode='P', 'T', 'C' (POOL, POOL/STARTUP, POOL/ONCALL, only on BS2000 systems)

  A KC_MODIFY_OBJECT call does not result in the exchange of the load module. Instead, the new version of the load module is marked.

  You must explicitly request the exchange of the load module by calling KC_CHANGE_APPLICATION or by restarting the application. By using several KC_MODIFY_OBJECT calls, you can mark several load modules which are then replaced when KC_CHANGE_APPLICATION is next invoked. If no KC_CHANGE_APPLICATION call is made in the same application run, the marked versions are then replaced when next the application is started.

  If you issue a KC_GET_OBJECT call between the KC_MODIFY_OBJECT call and the KC_CHANGE_APPLICATION call, then the marked version is already output as the current version, even if it has not yet been loaded. The KC_MODIFY_OBJECT call ensures that the new version of the load module is entered in the UTM tables as the current version and the currently loaded version is entered as the preceding version. You can tell from the change_necessary field whether a program exchange with KC_CHANGE_APPLICATION is still necessary in order to load the specified version.

  KDCPROG ("KDCPROG - Replace load modules/shared objects/DLLs")