KDCADMI program interface

You can use the program interface for administration (KDCADMI) to create administration programs specifically tailored to suit your application. This program interface is provided in C/C++ and COBOL. This manual describes the program interface for C/C++. Since the COBOL interface is broadly similar to the C/C++ interface, you can also use the description in this manual as a guide when creating COBOL administration programs. For additional information about creating administration programs in COBOL, see also the appendix, starting from "Program interface for administration in COBOL".

The program interface offers functions which go beyond the basic administration functions of KDCADM. The KDCADMI program interface also offers you the following additional functions:

• Functions with which you can modify the configuration dynamically:
  You can add new services (program units, transaction codes), clients, printers, user IDs, connections and session names for distributed processing by means of LU6.1, key sets, transaction codes for partner applications and service-controlled queues to the configuration dynamically, delete them from the configuration or change the properties of objects or application parameters.

• Inverse KDCDEF:
  You can generate control statements for generation tool KDCDEF from the configuration information stored in the KDCFILE.
  This means that changes to the configuration made during the application run can be transferred when the application is regenerated.

• Output all configuration data when information is requested:
  When information is requested for individual objects or application parameters, all the configuration data stored in the KDCFILE for this object or parameter is returned. In a custom-made administration program you can analyze and process exactly the data that is of interest for a given application. When requesting information, you can restrict output to those objects which satisfy particular criteria by entering these selection criteria when you make the call.

The following table lists the functions of KDCADMI and the operation codes which are used to call up program functions.

The KDCADMI program interface and all data structures are described in chapter "Program interface for administration - KDCADMI". Information about dynamic administration and inverse KDCDEF can be found in chapter "Changing the configuration dynamically" and chapter "Generating konfiguration statements from the KDCFILE".

KDCADMI Function	KDCADMI operation code
Exchange the entire application program without shutting down the application. BS2000 systems: Exchange sections of the application in the common memory pool which are marked for exchange. Unix, Linux and Windows systems: When doing this, you must specify whether the next higher version, the next lower version or the current version of the application program is to be loaded.	KC_CHANGE_APPLICATION
Generate a UTM diagnosis dump without terminating the application.	KC_CREATE_DUMP
Extend the configuration of an application dynamically to include new services (program units, transaction codes), clients, printers, user IDs, connections and session names for distributed processing by means of LU6.1, key sets, transaction codes for partner applications and service-controlled queues.	KC_CREATE_OBJECT
Start an inverse KDCDEF run online	KC_CREATE_STATEMENTS
Delete clients, printers, user IDs, services, connections and session names for distributed processing by means of LU6.1, key sets, transaction codes for partner applications and service-controlled queues from the configuration of the application.	KC_DELETE_OBJECT
Generate, activate or delete RSA key pair. Read public key of RSA key pair.	KC_ENCRYPT
Query the names and properties of objects, the current settings of application parameters and statistical information	KC_GET_OBJECT
On Unix, Linux and Windows systems: Permit a new sign-on for all users or for an individual user still recorded as signed on at a failed node application or who have/has a service bound to the failed node application. Release cluster user file lock after incorrectly terminated KDCDEF run. (Only in UTM cluster applications)	KC_LOCK_MGMT
Modify the properties of objects or application parameters, e.g.: change the settings for application parameters and timers, define current process numbers for the application, activate/deactivate traces, replace load modules/shared objects/DLLs in the application, disable/enable user IDs, transaction codes, clients/printers or connections to partner applications, establish and shut down connections to clients, printers and partner applications, activate OSI TP replacement connections, change the number of clients approved for an LTERM pool, change the assignment of clients/printers to LTERM partners, reset counter for statistics data, change keys in key sets, change the data access control for transaction codes, users and TAC queues.	KC_MODIFY_OBJECT
On Unix, Linux and Windows systems: Import application data from a terminated into a running node application (only for UTM cluster applications).	KC_ONLINE_IMPORT
Roll back transaction in PTC state (prepare to commit).	KC_PTC_TA
Only on BS2000 systems: Send message to a dialog terminal or to all active dialog terminals.	KC_SEND_MESSAGE
Terminate the UTM application run.	KC_SHUTDOWN
Establish connections to printers for which print jobs exist.	KC_SPOOLOUT
Switch the system log file (SYSLOG) in the application, activate/deactivate size monitoring on/off, modify the control value for size monitoring, request information via SYSLOG	KC_SYSLOG
Determine IP addresses of generated communication partners; on BS2000 systems: only for T-PROT=SOCKET	KC_UPDATE_IPADDR
Switch the user log file(s) to the next generation of file	KC_USLOG

Administration functions in the program interface for administration

In addition to the greater range of functions that you can use in administration programs you write yourself, administration programs which utilize the functions of the program interface also offer the following advantages:

• For administration by means of message queuing, you can choose any recipient for the results. This means that, depending on the result of a KDCADMI call, you can call up various follow-up transactions.

  This yields advantages for automatic and programmed administration.

• The results of an administration call can be analyzed and further processed in the program unit containing the The number of administration calls which are subject to transaction management and which are to be executed in a single transaction is, however, limited by the generated size of the restart area (generation statement MAX, parameter RECBUF, see openUTM manual “Generating Applications”).

• Only on BS2000 systems: You can use formats for the entry and output of administration programs.

Calls for administration functions must be made between the KDCS calls INIT and PEND. The data structures required for the exchange of data between openUTM and the program are predefined. For C/C++, the data structures are provided in the include file kcadminc.h (Unix, Linux and Windows systems) or in the include member kcadminc.h in the SYSLIB.UTM.070.C library (BS2000 systems).

For information about setting up a program, see chapter chapter "Writing your own administration programs".

openUTM on BS2000, Unix, Linux and Windows systems use the identical data structures. These data structures contain a few fields which only relate to one of these operating systems. In the other operating system, binary zeroes must be entered in these fields. The program is able to determine which operating system it is running on with the aid of a KDCADMI call.

Since the KDCADMI calls and the data structures used are platform-independent, you can use KDCADMI to create administration programs which:

• allow the user to administer several UTM applications from one “central” location. These UTM applications can even be running on different platforms. In particular, you can administer UTM applications on BS2000 systems from a UTM application on Unix, Linux or Windows system and vice versa. These applications can be running under different versions of openUTM.

• are portable. You can compile the same source of an administration program on any of the three platforms and link it to a UTM application from there.

For information on central administration of applications, see chapter "Central administration of several applications".

KDCADMI calls can, with one exception (termination of application run: KC_SHUTDOWN with subcode KC_KILL), be submitted in dialog as well as asynchronous services.

These dialog services can be started by users at the terminal, via UPIC clients or OpenCPIC partners, by a partner application or by HTTP clients.
The asynchronous services can be started by users at the terminal, by partner applications and by OpenCPIC partners or from a program unit.

The program interface for administration is subject to the compatibility guarantee, i.e. it is offered source-compatible across several different versions of openUTM. For this reason, administration programs do not need to be adapted to changes of version if they set those version as KDCADMI data structure version for which they had been developed. I.e. the administration programs should be recompiled as they are and then linked into a UTM application running under the follow-up version.