KDCAPPL allows you to perform the following actions:
Change the timer settings and maximum values that you have generated in the KDCDEF control statement MAX.
Define the number of processes (TASKS) that can be involved in an application simultaneously. If you wish to reduce the current number of processes, you should refer to the information provided in chapter "Possible measures".
Define the maximum number of processes that are permitted to process asynchronous services or services with blocking function calls (e.g. the KDCS call PGWT) simultaneously. The maximum possible number of these processes depends on the total number of processes in the application and on the maximum number of processes defined in the KDCDEF statement MAX that are entitled to process services of this kind.
Control cache memory paging.
Switch the accounting and calculation phase of the UTM accounting procedure on and off
Enable and disable data compression
Establish a connection to all printers for which messages are present.
Exchange the entire application program during live operation. This enables you, without terminating the application, to change program units and to take new program units that you have included dynamically in the configuration and add them to the application program.
In standalone UTM applications on BS2000 systems, load modules whose versions have previously been modified with KDCPROG are therefore also swapped in the Common Memory Pool.
Switch over the system log files for the application (SYSOUT and SYSLST or stderr and stdout) during live operation. This avoids a hard disc bottleneck, since it allows log files to be evaluated and files which are no longer required to be deleted or archived.
In addition, you can also enable or disable provision of data to the openSM2 software monitor for the application.
Period of validity of the changes
The changes made with KDCAPPL last for no longer than the duration of the current application run.
Exception:
A program exchange (PROGRAM operand) remains effective beyond the end of the current application run, i.e. when the application is next started, the most recently loaded version of the application program is reloaded. In the case of a restart, UTM attempts to load the new application program even if a previous attempt to initiate a program exchange (in the previous application run) was unsuccessful.
Effect in cluster operation
The effect on cluster applications is described in the sections devoted to the individual operands since some of the changes made with KDCAPPL apply locally to the node whereas others take effect globally in the cluster. Changes made locally in a node apply at the most for the duration of the current node application run.
Changes made globally in the cluster apply at the most for the duration of the current UTM cluster application run.
KDCAPPL [ ,ACCOUNT={ ON | OFF } ]
[ CACHE=%_utm_pages ]
[ ,CALC={ ON | OFF } ]
[ ,CONCTIME=con_control_time_sec ]
[ ,CONRTIME=con_request_time_min ]
[ ,DATA-COMPRESSION={ ON | OFF } ]
[ ,MAXASYN=number_tasks ]
[ ,MAX-CONN-USERS=number_users ]
[ ,PGWTTIME=wait_time_sec ]
[ ,PROGRAM={NEW | OLD | SAME} ]
[ ,PTCTIME=wait_time_sec ]
[ ,RESWAIT-PR=wait_time_sec ]
[ ,RESWAIT-TA=wait_time_sec ]
[ ,SPOOLOUT=ON ]
[ ,SYSPROT=NEW ]
[ ,TASKS=number_tasks ]
[ ,TASKS-IN-PGWT=number_tasks ]
[ ,TERMWAIT=wait_time_sec ]
[ ,SM2={ ON | OFF } ]
For administration using message queuing you must specify KDCAPPLA.
ACCOUNT= | enables and disables the UTM accounting phase. | |||||||||||||||||||||||||
In UTM cluster applications, the operand applies globally in the cluster. On BS2000 systems enabling the accounting phase only becomes effective if record type UTMA is enabled on BS2000 Accounting. The command KDCAPPL ACC=ON is not rejected if record type UTMA is not enabled, since openUTM only detects this when writing an accounting record. The value set in the KDCDEF control statement in ACCOUNT ACC= applies when the application is started. For further details on UTM Accounting see also the openUTM manual “Using UTM Applications”. Note for BS2000 systems
| ||||||||||||||||||||||||||
CACHE=%_utm_pages | ||||||||||||||||||||||||||
Defines the maximum percentage of pages in cache memory that can be stored on KDCFILE when bottlenecks develop. In UTM cluster applications, the operand applies globally in the cluster. CACHE allows you to adjust the percentage defined during KDCDEF generation in the MAX statement for the duration of the current application run. UTM swaps out at least 8 UTM pages in a paging operation, even a smaller value is calculated. Minimum value: 0 (in this case, 8 pages are swapped out) If a value < 100 was specified at generation for number in the CACHESIZE operand of the MAX statement, rounding errors can occur at that output of %_utm_pages of a subsequent KDCAPPL command. | ||||||||||||||||||||||||||
CALC= | Enables the calculation phase of UTM Accounting. In UTM cluster applications, the operand applies globally in the cluster. | |||||||||||||||||||||||||
ON | Enables the calculation phase. | |||||||||||||||||||||||||
OFF | Disables the calculation phase again. When the application is started, the value set in ACCOUNT ACC= in the KDCDEF control statement applies. For further details on UTM Accounting see also the openUTM manual “Using UTM Applications”. | |||||||||||||||||||||||||
CONCTIME=con_control_time_sec | ||||||||||||||||||||||||||
(Connection Control Time) In UTM cluster applications, the operand applies globally in the cluster. CONCTIME=0 means
Maximum value: 32767 | ||||||||||||||||||||||||||
CONRTIME=con_request_time_min | ||||||||||||||||||||||||||
(connection request time) In UTM cluster applications, the operand applies globally in the cluster. CONRTIME relates to connections to the following partners:
If no connection is established between partners configured with automatic connection setup (when an application is started or when an administration function requests a connection), UTM attempts to establish a new connection, or to re-establish the connection at the intervals specified in CONRTIME. If CONRTIME=0, UTM makes no attempt to re-establish a connection. Maximum value: 32767 | ||||||||||||||||||||||||||
DATA-COMPRESSION | ||||||||||||||||||||||||||
Enables or disables data compression. Any modification applies beyond the end of an application. The UTM pages saved per compression can be queried by means of KDCINF STAT command (see section "type=STATISTICS" in chapter "Output from KDCINF (examples)"), the program interface (see chapter "kc_curr_par_str - Current values of the application parameters"), or WinAdmin/WebAdmin. In UTM cluster applications, the operand applies globally in the cluster. | ||||||||||||||||||||||||||
ON | Switches data compression on. | |||||||||||||||||||||||||
OFF | Switches data compression off. | |||||||||||||||||||||||||
MAXASYN=number_tasks | ||||||||||||||||||||||||||
Specifies the maximum number of processes in the application that are allowed to accept jobs for asynchronous transaction codes at the same time (see KC_MODIFY_OBJECT, obj_type=KC_TASKS_PAR as of chapter "obj_type=KC_MAX_PAR", mod_max_asyntasks parameter). In UTM cluster applications, the operand applies locally in the node. | ||||||||||||||||||||||||||
MAX-CONN-USERS=number_users | ||||||||||||||||||||||||||
Defines the maximum number of users who can have connections to a UTM application at the same time. This restriction enables you to prevent your application from becoming overloaded. In UTM cluster applications, the operand applies locally in the node. openUTM checks the number of active users when another user signs on, and rejects the connection attempt if the number of users defined in number_users are already signed on. This restriction does not apply to user IDs with administration privileges. If, at the time of your KDCAPPL call, more than number_users users are working on the system, none of these users are forced to quit their application. However, no further connections will be permitted until the number of connected users falls to less than number_users. If an application has been generated without user IDs, number_users restricts the number of dialog partners who can be connected to the application simultaneously. If a number is specified for number_users which is greater than the number of generated dialog LTERM partners, number_users has no effect. Dialog LTERM partners are all the LTERM partners generated with USAGE=D, LTERM partners of the LTERM pools and - with BS2000 - the LTERM partners UTM generates internally for multiplex connections. number_users = 0 means that there is no restriction on the number of users or dialog partners working on the system. Maximum value:
Minimum value: 0 (no restriction). | ||||||||||||||||||||||||||
PGWTTIME=wait_time_sec | ||||||||||||||||||||||||||
Changes the maximum time in seconds defined during generation for which a program unit can wait for messages to arrive after a blocking function call; it also displays the currently set value for this wait time. The wait time is generated in the KDCDEF statement MAX with the operand PGWTTIME. Blocking function calls are calls where control is not returned until a response has been received by the program unit (e.g. the KDCS call PGWT). In UTM cluster applications, the operand applies globally in the cluster. During this wait time, a process in the UTM application is reserved exclusively for this program unit. Maximum value: 32767 | ||||||||||||||||||||||||||
PROGRAM= | ||||||||||||||||||||||||||
Exchanges the entire application program during live operation (see the corresponding openUTM manual “Using UTM Applications”). Requirements for exchanging a program using KDCAPPL PROGRAM=
In UTM cluster applications, the operand applies globally in the cluster for all the node applications that are currently running. Other KDCAPPL operands have no effect in conjunction with PROGRAM. KDCAPPL PROGRAM= is rejected if a program is being exchanged at the time this call is submitted. Only the values NEW and SAME are allowed on BS2000 systems. Both values have the same effect. | ||||||||||||||||||||||||||
NEW | The entire application program is to be exchanged. BS2000 systems KDCAPPL PROGRAM=NEW is not permitted if the application has been started in interactive mode. In a UTM application on a BS2000 system the application program is unloaded in all processes and then re-loaded. When this is done, the current versions of the load modules are loaded. If a load module is generated with *HIGHEST-EXISTING, then the highest version of the load module existing in the library is loaded. Program units in common memory pools are also exchanged at the same time. The version of load modules to be loaded during a program exchange must be declared in advance with KDCPROG. Before the program is exchanged, several such load modules in the common memory pool can be earmarked for exchange by several KDCPROG calls. In a standalone UTM application, it is possible to mark multiple load modules in the Common Memory Pool for exchange by means of multiple KDCPROG calls prior to exchange. Termination of the application program followed by a reboot also causes all load modules generated with load mode ONCALL to be unloaded from the application. This means that static parts of the application can also be exchanged when the application is linked before. In a UTM cluster application, application program exchange is initiated automatically as soon as the version of a load module in a Common Memory Pool is modified (via KDCPROG). Unix, Linux and Windows systems In a UTM application on Unix, Linux and Windows systems, openUTM loads the application program from the next highest file generation present in the file generation directory filebase/PROG (Unix and Linux systems) or filebasePROG (Windows systems) if the UTM tool KDCPROG is used to administer the different versions of the application program (including the one that is currently loaded) in the PROG file generation directory. | |||||||||||||||||||||||||
SAME | On Unix, Linux and Windows systems, openUTM loads the application program from the same file generation as is located in the file generation directory filebase/PROG (Unix and Linux systems) or filebase\PROG (Windows systems) if the different versions of the application program (including the currently loaded program) are administered using the UTM tool KDCPROG in the PROG file generation directory. If you have not created a file generation directory, then KDCAPPL PROG=SAME reloads the application program (utmwork) that is located in the base directory filebase. On BS2000 systems, SAME has the same effect as NEW. | |||||||||||||||||||||||||
OLD | (Only on Unix, Linux and Windows systems) openUTM will not accept a new program exchange until the exchange has been completed for all the processes. If errors occur in the first process when the new application program is started then openUTM issues the message K075 and loads the original application program again. When the exchange of the application program has been terminated for all the processes, openUTM issues message K074. On Unix, Linux and Windows systems, you can query the generation of the currently loaded application program, for example with KDCINF SYSP. | |||||||||||||||||||||||||
PTCTIME=wait_time_sec | ||||||||||||||||||||||||||
Only for applications with distributed processing: If KDCSHUT WARN or GRACE has already been issued for the application and the value of PTCTIME is not 0, then the waiting time is chosen independently of PTCTIME in such a way that the transaction is rolled back before the application is terminated in order to avoid abnormal termination of the application with ENDPET, if possible. In UTM cluster applications, the operand applies globally in the cluster. The value 0 indicates that the system can wait for an unrestricted length of time for a confirmation. Maximum value: 32767 | ||||||||||||||||||||||||||
RESWAIT-PR=wait_time_sec | ||||||||||||||||||||||||||
The maximum time in seconds that one process can wait for resources that are being used by another process. If this period of time is exceeded, the application terminates with an error message. In UTM cluster applications, the operand applies globally in the cluster . If you specify RESWAIT-PR, please note that the value for wait_time_sec must be at least as long as the longest processing time (real time) required for the following cases:
Maximum value: 32767 | ||||||||||||||||||||||||||
RESWAIT-TA=wait_time_sec | ||||||||||||||||||||||||||
Maximum time in seconds for which a program unit is to wait for a resource that is being used by another transaction: GSSBs, ULSs, TLSs. In UTM cluster applications, the operand applies globally in the cluster. The wait time specified in wait_time_sec is meaningless if the lock is effected by a multi-step transaction which is waiting for an input message after a PEND KP or a PGWT KP call. In this event, all program units with access to the locked resource immediately receive a KCRCCC return code (without wait time wait_time_sec). RESWAIT-TA= 0 indicates that the process is not to wait. Any program unit run which attempts to access the locked resource immediately receives a KCRCCC return code. The real wait time depends on the precision with which the information exchange wait times are set in the operating system. Maximum value: 32767 | ||||||||||||||||||||||||||
SPOOLOUT=ON | ||||||||||||||||||||||||||
Causes UTM to establish a connection to all printers for which messages exist at the time of the call and which are not yet connected to the application. This enables you to output all messages to those printers to which it is possible to establish a connection (e.g. before terminating the application). In UTM cluster applications, the operand applies locally in the node. | ||||||||||||||||||||||||||
SYSPROT=NEW | ||||||||||||||||||||||||||
The log files of the application are switched over. In UTM cluster applications, the operand applies globally in the cluster for all the node applications that are currently running. The names of the new log files are formed as follows: BS2000 systems: SYSOUT: prefix Only SYSLST is switched over if the application is started interactively.
| ||||||||||||||||||||||||||
TASKS=number_tasks | ||||||||||||||||||||||||||
Specifies the current number of processes in the application. UTM switches processes on or off accordingly (see KC_MODIFY_OBJECT, obj_type=KC_TASKS_PAR as of chapter "obj_type=KC_MAX_PAR", mod_max_tasks parameter). In UTM cluster applications, the operand applies locally in the node. Maximum value: Minimum value:
A certain amount of time is required for starting and terminating the UTM processes. After entering KDCAPPL TASKS= you should therefore first wait for the result of the call, then use KDCINF SYSPARM to check it before issuing any more KDCAPPL TASKS= calls. Failure to do so can lead to start errors. | ||||||||||||||||||||||||||
TASKS-IN-PGWT=number_tasks | ||||||||||||||||||||||||||
Defines the number of processes in the UTM application that are allowed to process program units in which blocking calls (e.g. the KDCS call PGWT) are permitted (see KC_MODIFY_OBJECT, obj_type=KC_TASKS_PAR as of chapter "obj_type=KC_MAX_PAR", mod_max_tasks_in_pgwt parameter). In UTM cluster applications, the operand applies locally in the node. The command is rejected if you enter TASKS-IN-PGWT=0, although MAX TASKS-IN-PGWT >0 was generated. | ||||||||||||||||||||||||||
TERMWAIT=wait_time_sec | ||||||||||||||||||||||||||
Maximum time in seconds allowed to elapse in a multi-step transaction (i.e. in the PEND KP program) between output to a dialog partner (terminal, UPIC client, TS application or job-submitting service in a partner application) and the ensuing dialog response. If this time exceeds wait_time_sec the transaction is rolled back. The connection to the dialog partner is shut down. In UTM cluster applications, the operand applies globally in the cluster. Maximum value: 32767 | ||||||||||||||||||||||||||
SM2= | ||||||||||||||||||||||||||
Switches the data supply to openSM2 on and off. It is only possible to supply data to openSM2 if the generation parameters permit openSM2 event logging to be switched on (KDCDEF statement MAX, operand SM2=ON or OFF). If SM2=NO is generated, the administrator will not be able to switch on the data supply to openSM2. The following applies in UTM cluster applications: | ||||||||||||||||||||||||||
ON | openUTM supplies data to openSM2. | |||||||||||||||||||||||||
OFF | openUTM does not supply data to openSM2. | |||||||||||||||||||||||||
Output from KDCAPPL
The new and old values of the parameter are always displayed (with the exception of KDCAPPL PROG=).
NEW OLD TERMWAIT ... ... RESWAIT-PR ... ... RESWAIT-TA ... ... CONRTIME ... ... CURR TASKS ... ... MAXASYN ... ... TASKS-IN-PGWT ... ... CACHE ... ... ACCOUNT ... ... CALC ... ... SM2 ... ... MAX-CONN-USERS ... ... PGWTTIME ... ... CONCTIME ... ... (1.) PTCTIME ... ... (1.) PROGRAM FGG ... ... (2.)
The lines for PTCTIME and CONCTIME are only output via LU6.1 or OSI TP for an application with distributed processing.
The line for PROGRAM FGG is only output if in a UTM application on a Unix, Linux or Windows system the entire application program is to be exchanged by means of KDCPROG. In such cases, the new generation number of the application program is output under NEW and the old generation number is output under OLD. Once all the processes in the program have been exchanged, UTM issues message K074.