KDCPROG allows you to use the BLS interface to replace load modules in a UTM application on a BS2000 system, or to replace shared objects in a UTM application on Unix, Linux and Windows systems if you are working with the function “Program exchange with shared objects”. See also the openUTM manual “Generating Applications” and the corresponding openUTM manual “Using UTM Applications”.
On Windows systems, shared objects are realized using DLLs. Details pertaining to handling the DLLs are also described in the openUTM manual “Using UTM Applications on Unix, Linux and Windows Systems”.
Requirements for program exchange using KDCPROG
You can replace or reload sections of an application program if they satisfy the following parameters:
The program sections to be replaced must have been generated as separate load modules/shared objects/DLLs.
Every load module or shared object/DLL to be replaced must have been generated statically using a LOAD-MODULE statement (BS2000 systems) or a SHARED OBJECTS statement (Unix, Linux and Windows systems).
The load modules/shared objects/DLLs must not have been statically linked to the application program.
On BS2000 systems, the load modules to be replaced must not have been loaded in system memory (class 4 memory), nor in a global common memory pool (generated with SCOPE=GLOBAL).
To enable openUTM to process the command, a load module/shared object/DLL must exist with the specified name and version defined in version in the program library or directory that was assigned to it during KDCDEF generation:
LOAD-MODULE statement, operand LIB (BS2000) or
SHARED-OBJECT statement, operand DIRECTORY (Unix, Linux and Windows systems).
BS2000 systems
If no load module with the specified name and version exists in this program library, the administration command is rejected and the previously loaded load module remains loaded. In addition, the message K234 is output.
Unix, Linux and Windows systems
If shared object/DLL with the version an defined in version exists in the specified directory, the previously loaded shared object/DLL will be unloaded and a message issued.
If you then call KDCPROG again, you can load the load module/shared/DLL object by specifying a version of the load module/shared object that already exists in the library in version, or by placing the missing load module/shared object/DLL with the specified version in the program library/program directory.
How to implement a program exchange
The way a program exchange is implemented depends on the generated load mode of the load module/shared object/DLL.
You generate the load mode in the LOAD-MODULE statement (BS2000 systems) or in the SHARED-OBJECT statement (Unix, Linux and Windows systems), in both cases in the LOAD-MODE operand.
LOAD-MODE=STARTUP
(The load module/shared object/DLL is loaded as a separate unit when the application starts.)
This exchange operation is performed for each process not later than after the next job is processed, without first terminating the current application program. Several processes in the application can be terminated simultaneously. Until the program exchange has been completed for all processes in the application, you are not allowed to initiate any further exchanges with KDCPROG.The KDCPROG call merely initiates a program exchange. The actual process of program exchange can take some considerable time. openUTM informs you of the success or failure of the program exchange operation with messages to SYSOUT and SYSLOG (BS2000 systems) or stdout and stderr (Unix, Linux and Windows systems).
LOAD-MODE=ONCALL
(Loaded whenever a program unit is called up out of the load module/shared object/DLL for the first time.)
Exchange is performed for every process even if a program unit from this load module/shared object is called next time in the same process. At any given time, several processes in the application can be replaced simultaneously.LOAD-MODE=(POOL, POOL/STARTUP, POOL/ONCALL, only on BS2000 systems) (The public slice of the load module is loaded into a common memory pool.)
Program exchange operation is not initiated by the KDCPROG call. KDCPROG only causes the new version to be flagged. The new version of the load module is not loaded into the common memory pool until the following exchange of the entire application program with KDCAPPL PROG=NEW. In this event, another KDCPROG call can follow immediately after the call from KDCPROG.
You can flag several load modules using several KDCPROG calls which are then replaced in response to the next KDCAPPL PROG=NEW. If no KDCAPPL PROG=NEW follows in the same application run, the flagged versions are replaced after the next application start.
Effect in UTM cluster applications on Unix, Linux and Windows Systems:
In UTM cluster applications, KDCPROG applies globally to the cluster. Program exchange is performed in all running node applications.
Period of validity for a program exchange
The change remains in force after the end of the application.
KDCPROG VERSION={ version | *HIGHEST-EXISTING | *UPPER-LIMIT }
BS2000 systems:
, LOAD-MODULE=lmodname
Unix, Linux and Windows systems:
, SHARED-OBJECT=shared-object-name
For administration using message queuing you must enter KDCPROGA.
VERSION=version
Version of the load module/shared object/DLL which has to be loaded. The value for version must not exceed 24 characters in length.
BS2000 systems
In UTM applications on BS2000 systems you must always specify the next 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.
When the exchange is initiated, the library to which the load module was assigned for KDCDEF generation (see also KDCDEF statement LOAD-MODULE...,LIB=) must contain an element with the name lmodname and the version specified in version.
If VERSION=*HIGHEST-EXISTING is specified, then the highest version of the load module existing in the library is detected and loaded.
If VERSION=@ or *UPPER-LIMIT is specified, then the load module is loaded which was last entered in this PLAM library without an explicit version specification. If you work with explicit versions in LMS, you cannot use @ or *UPPER-LIMIT as the load module version.
If a load module is generated with LOAD-MODE=POOL, (POOL,STARTUP) or (POOL,ONCALL) and with the version *HIGHEST-EXISTING, only *HIGHEST-EXISTING can be specified as the version. 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.
You cannot replace load modules that have been linked statically to the application program (load mode STATIC).
Similarly, load modules which have the STARTUP load mode and contain TCB entries can also not be replaced.
Unix, Linux and Windows systems
In UTM applications running on Unix, Linux or Windows systems you must enter the version name if the shared object was generated with the ONCALL load mode.
Entering the version name is optional for shared objects/DLLs with the STARTUP load mode if you are not using the version concept.
LOAD-MODULE=lmodname (only on BS2000 systems)
Name of the load module to be replaced. This can be the name of an OM or an LLM. The load module (with this name) must have been configured for KDCDEF generation with a LOAD-MODULE statement. You can only enter one name for each KDCPROG call.
The name must not be more than 32 characters long.
SHARED-OBJECT=shared-object-name (only on Unix, Linux and Windows systems)
Name of the shared object/DLL to be replaced. The name must have been generated with a SHARED-OBJECT statement. For each KDCPROG call you can only specify one name.
The name must not be more than 32 characters long.
Output from KDCPROG
After a KDCPROG call is placed, the following information is output to the administrator terminal:
Output for UTM applications on BS2000 systems
LOAD-MODULE lmodname VERSION (GENERATED) generated element version VERSION (PREVIOUS) old element version VERSION (CURRENT) new element version LIBRARY name of program library LOAD MODE STARTUP | ONCALL | POOL | POOL/STARTUP | POOL/ONCALL
Output for UTM applications running on Unix, Linux or Windows systems
SHARED-OBJECT shared object name VERSION (PREVIOUS) old version VERSION (CURRENT) new version DIRECTORY name of program directory LOAD MODE STARTUP | ONCALL
Explanation of the output
LOAD-MODULE
Name of the load module on BS2000 systems
SHARED-OBJECT
Name of the shared objects/DLL on Unix, Linux and Windows systems
VERSION (GENERATED)
Generated version of the load module
VERSION (PREVIOUS)
Previously loaded version of the load module/shared object/DLL
VERSION (CURRENT)
Version of the load module/shared object which is to be loaded
LIBRARY
Name of the program library from which the load module (BS2000 systems) is loaded.
DIRECTORY
Name of the directory from which the shared object/DLL is loaded (Unix, Linux and Windows systems).
LOAD MODE Load mode for the load module/shared object/DLL:
STARTUP
The load module/shared object/DLL is loaded as a separate unit when the application starts.
ONCALL
The load module/shared object/DLL is loaded whenever a program unit is called from the load module for the first time.
Only on BS2000 systems:
POOL
The load module is loaded into the common memory pool when the application starts. The load module does not contain a private slice.
POOL/STARTUP
The public slice of the load module is loaded into the common memory pool when the application starts. The private slice belonging to the load module is then loaded into the local process memory.
POOL/ONCALL
The public slice of the load module is loaded into the common memory pool when the application starts. The private slice belonging to the load module is loaded into the local process memory when the first program unit assigned to this load module is called.
Program exchange messages with KDCPROG
Once the exchange of application units generated by a STARTUP (and POOL with BS2000 systems) load mode is complete, the following message is output to SYSOUT and SYSLOG (BS2000 system) or stdout and stderr (Unix, Linux or Windows system):
K074 Program exchange completed ...
If errors occur when application units generated with STARTUP (and POOL with BS2000 systems) load mode are being replaced, the following message is output to SYSLST and SYSLOG (BS2000 system) or stdout and stderr (Unix, Linux or Windows system):
K075 Program exchange aborted by task/process ..
If errors occur during exchange on BS2000 systems, message K078 together with the error cause is output to SYSOUT.