Description of the data areas to be supplied

This section contains a general description of the parameters and data that can be passed to UTM when calling KDCADMI.

More detailed information concerning how to assign data to the identification area, selection area, data area and fields of the parameter area for individual operations can be found in section "KDCADMI operation codes".

The following symbols have the following meanings:

--> The field is an input field. You can pass information to UTM using this field.

<-- The field is an output field. UTM returns information to the administration program in this field.

Parameter area

You can instruct UTM to perform a specific operation using the parameter area. The opcode, subopcode1 and subopcode2 fields are provided for this purpose. In the obj_type field, you specify the object type of the target object.

After processing, UTM stores the return code and the length of the data returned in the parameter area. You can determine if the call was successful or not from the return code.

The parameter area is defined as followed by the structure kc_adm_parameter:

struct kc_adm_parameter

int version;

KC_ADM_RETCODE retcode;

int version_data;

KC_ADM_OPCODE opcode;

KC_ADM_SUBOPCODE subopcode1;

KC_ADM_SUBOPCODE subopcode2;

KC_ADM_TYPE obj_type;

int obj_number;

int number_ret;

int id_lth;

int select_lth;

int data_lth;

int data_lth_ret;

Input fields in the kc_adm_parameter structure (hereafter indicated using the -->character) that are not used must always be set to binary zero. The version, version_data and opcode fields must contain data every time KDCADMI is called.

The fields in the data structure have the following meanings:

-->version

Designates the version of the program interface used by the user program.

The version of the program interface indicates the variant of the program interface and the layout of the parameter areas passed at call time. You must explicitly specify the version of the program interface on each call of KDCADMI. So far, only KC_ADMI_VERSION_1 has been defined as a version.

If the variant of the program interface is modified in a subsequent version then the version of the program interface is increased. If the extensions are compatible and you would like to continue to use the existing program interface in the new openUTM version then you do not need to adapt your existing administration programs and can continue to specify the version of the interface as KC_ADMI_VERSION_1. If you want the administration program to use the new program interface then you must adapt your programs and specify the program interface version of the current openUTM version in version.

The interface is designed to be source-compatible across multiple openUTM versions.

<--retcode

In the retcode field, UTM returns the code of the function call.

There are general and function-specific return codes.
The general return codes can be returned by all functions. They are described in "Return codes".
The function-specific return codes only occur in connection with certain program interface calls, and they are listed in the relevant call descriptions.

If the entire length of data in the parameter area cannot be accessed, then the KDCS return code in the return area of the communication area for the service processing the KDCADMI call is assigned '70Z', the KCRCDC return code is assigned 'A100', and the service is aborted with PEND ER.

The retcode field must be assigned the constant KC_RC_NIL before the function is called.

-->version_data

Version of the data structures used.

The version of the data structures determines the layout of the data structures used. You must specify the value of version_data explicitly for each KDCADMI call. In openUTM V7.0, the constant KC_VERSION_DATA_11 should be used for version_data.

KC_VERSION_DATA (without suffix) always refers to the current version of the data structures. Programs that want to benefit from the source compatibility of the interface should not use the constant KC_VERSION_DATA, but for version_data should always specify the version constant KC_VERSION_DATA_xx for the interface version for which the program was written. KC_VERSION_DATA_11 is the version valid for openUTM V7.0, while KC_VERSION_DATA_10 refers to the version valid for openUTM V6.5 for example.

If the layout of the data structures is modified to remain object-compatible, KC_VERSION_DATA is not increased and the program units can run in the new UTM version.

If the layout of the data structures changes in a way that is incompatible in an openUTM version, for example if the data structures receive new fields and therefore become larger, then the version number of the data structure is incremented. The constants KC_VERSION_DATA and KC_VERSION_DATA_10 are defined in the same include file as the data structures. Because the interface is source-compatible, program units must be only recompiled in this case.

-->opcode, subopcode1, subopcode2

In these fields you tell UTM which action to execute. The opcode field must be assigned a value each time KDCADMI is called. This field determines which operation will be executed. In the subopcode1 and subopcode2 fields, you can specify in more detail what action should be taken depending on the value of opcode.

The values you will need to use for opcode to execute certain operations are summarized in the following table. The operation codes indicated by a (*) are socalled standard operations that are explained in more detail in the section "Data structures for object and parameter types".

Function	Value of opcode
Replace the entire application program. BS2000 systems: Replace application sections that have been marked for exchange in the Common Memory Pool. Unix, Linux and Windows systems: In subopcode1 you specify whether the next highest, next lowest or the current version of the application program is to be loaded.	KC_CHANGE_APPLICATION
Create a UTM dump	KC_CREATE_DUMP
Create a new object in the configuration	KC_CREATE_OBJECT (*)
Create KDCDEF control statements online (inverse KDCDEF)	KC_CREATE_STATEMENTS
Delete an object, i.e. remove it from the configuration	KC_DELETE_OBJECT (*)
Generate, activate, delete or read RSA key pairs for data encryption ot the communication with clients	KC_ENCRYPT
Query information on objects and application parameters. You control the type and amount of detail of information returned using subopcode1 and subopcode2.	KC_GET_OBJECT (*)
Only in UTM cluster applications: 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.	KC_LOCK_MGMT
Modify object properties or application parameters	KC_MODIFY_OBJECT (*)
Only in UTM cluster applications: Import TACs, TAC queues and open asynchronous services from a terminated into a running node application.	KC_ONLINE_IMPORT
Roll back transaction in PTC state.	KC_PTC_TA
Only on BS2000 systems: Send a message to one dialog terminal or to all dialog terminals connected to the application.	KC_SEND_MESSAGE
Terminate an application run. Specify how the application is to be terminated (kill, normal termination) in subopcode1 and subopcode2 . In the case of UTM cluster applications, specify whether an individual node application or the complete UTM cluster application is to be terminated.	KC_SHUTDOWN
Establish connections to printers for which messages have been queued.	KC_SPOOLOUT
Carry out an operation on the system log file SYSLOG. You specify which operation is to be executed using subopcode1.	KC_SYSLOG
Update the IP address of an individual or of all communication partners. On BS2000 systems, the communication partners must be generated with T-PROT=SOCKET.	KC_UPDATE_IPADDR
Switch to the next generation of the user log file(s)	KC_USLOG

The information you may or must supply in the other fields of the parameter area and in the identification area, selection area and data area are dependent on the opcode passed. For each operation code (value of opcode), section "Calling the KDCADMI functions" contains a description of the operations that can be carried out and of the information that the data area must contain to be passed to UTM in order to carry out these operations. The list is ordered alphabetically according to the operation code.

-->obj_type

The obj_type field must contain either the type of the target object or the type of the application parameter whose value is queried or is to be changed.

The object or parameter types that you can enter depend on which operation you require, and therefore on the values in the opcode, subopcode1 and subopcode2 fields

The two tables below contain the objects and parameter types that are supported for the standard operations in UTM. Standard operations are:

• Display

• Create

• Modify

• Delete

The column “opcode” in the table contains the operation codes for which each object type or parameter type can be specified. The following abbreviations are used:

• CRE for KC_CREATE_OBJECT (Create)

• DEL for KC_DELETE_OBJECT (Delete)

• GET for KC_GET_OBJECT (Show)

• MOD for KC_MODIFY_OBJECT (Modify)

Object types

Object type	Value of obj_type	opcode
Abstract syntax for communication via OSI TP	KC_ABSTRACT_SYNTAX	GET
OSI  TP access points for local application	KC_ACCESS_POINT	GET
Application context for communication via OSI  TP	KC_APPLICATION_CONTEXT	GET
Names for the local application that were generated with KDCDEF (in a BCAMAPPL statement or in MAX APPLINAME)	KC_BCAMAPPL	GET
Only on BS2000 systems: Names of the Character Sets (CHAR-SET Statement)	KC_CHARACTER_SET	GET
Names and properties of a node application in a UTM cluster application	KC_CLUSTER_NODE	GET, MOD
Connections for distributed processing via LU6.1	KC_CON	GET, CRE, DEL
Database connection	KC_DB_INFO	GET, MOD
Only on BS2000 systems: Edit options for screen output in line mode	KC_EDIT	GET
Global secondary storage areas for KDCS program units used to exchange data between services (GSSB)	KC_GSSB	GET
Names and properties of the HTTP descriptors (HTTP-DESCRIPTOR Statement)	KC_HTTP_DESCRIPTOR	GET
Keysets for the application. Keysets determine the access privileges of clients and users accessing services and LTERM partners.	KC_KSET	GET, MOD, CRE, DEL
Load modules of a UTM application on BS2000 systems or the shared objects/DLLs of a UTM application on Unix, Linux or Windows systems	KC_LOAD_MODULE	GET, MOD
LPAP partner for connecting partner applications for distributed processing via LU6.1	KC_LPAP	GET, MOD
Sessions for distributed processing via LU6.1	KC_LSES	GET, MOD, CRE, DEL
Local transaction codes for services provided by partner applications for distributed processing via LU6.1 or OSI TP	KC_LTAC	GET, MOD, CRE, DEL
LTERM partner for connecting clients and printers	KC_LTERM	CRE, DEL, GET, MOD
User-defined message module	KC_MESSAGE_MODULE	GET
Only on BS2000 systems: Multiplex connections 1	KC_MUX	GET, MOD
Associations with partner applications for distributed processing via OSI TP	KC_OSI_ASSOCIATION	GET
Connections for distributed processing via OSI TP	KC_OSI_CON	GET, MOD
OSI-LPAP partner for connecting partner applications for distributed processing via OSI TP	KC_OSI_LPAP	GET, MOD
Transactions in PTC state	KC_PTC	GET
Program units of the UTM application and VORGANG exits	KC_PROGRAM	CRE, DEL, GET
Clients and printers. "Clients" can be: terminals, UPIC clients, TS applications	KC_PTERM	CRE, DEL, GET, MOD
Temporary queues	KC_QUEUE	GET
Allocation of UTM function keys	KC_SFUNC	GET
Properties of sign-on procedure	KC_SIGNON	GET
IP subnets	KC_SUBNET	GET
Transaction codes for local services and TAC queues	KC_TAC	CRE, DEL, GET, MOD
TAC classes for the application	KC_TACCLASS	GET, MOD
LTERM pools for the application	KC_TPOOL	GET, MOD
Transfer syntax for communication via OSI TP	KC_TRANSFER_SYNTAX	GET
User IDs of the application, including queues	KC_USER	CRE, DEL, GET, MOD
User IDs of the application including their queues (optimized access for UTM cluster applications)	KC_USER_FIX, KC_USER_DYN1, KC_USER_DYN2	GET

Parameter types

Parameter type	Value of obj_type	opcode
Current statistics values on the capacity utilization of a UTM cluster application	KC_CLUSTER_CURR_PAR	GET, MOD
Properties of a UTM cluster application (e.g. name of the cluster filebase, node application monitoring settings) as well as current settings (e.g. number of started node applications)	KC_CLUSTER_PAR	GET, MOD
Current settings of the application parameters and statistics concerning the application capacity utilization	KC_CURR_PAR	GET, MOD
Parameters for diagnosis and UTM Accounting	KC_DIAG_AND_ACCOUNT_PAR	GET, MOD
Data for dynamic configuration: Number of existing and reserved objects, i.e. the total number of objects available in the individual object tables and the number of objects that can still be configured dynamically	KC_DYN_PAR	GET
Application name, KDCFILE name and maximum values for the application, such as the size of the cache, size and number of storage areas for KDCS program units, and the maximum number of processes permitted for the application	KC_MAX_PAR	GET, MOD
Name, type and format of a user-specific message destination	KC_MSG_DEST_PAR	GET
Current page pool assignment	KC_PAGEPOOL	GET
General information on the generated temporary queues: maximum number of queues, maximum number of messages for a queue, behavior of full queues.	KC_QUEUE_PAR	GET
System parameters: Type and version of the operating system, name of the computer and the basic application data (application name, application with or without distributed processing, etc.)	KC_SYSTEM_PAR	GET
Process parameters for the application: Maximum and current number of application processes as well as of the processes available for processing asynchronous jobs and program unit runs with blocking calls.	KC_TASKS_PAR	GET, MOD
Application timer	KC_TIMER_PAR	GET, MOD
Global values for distributed processing, except for the timer defined for distributed processing	KC_UTMD_PAR	GET

Data structures for object and parameter types

For each of the object and parameter types associated with the standard operations, a data structure is provided in the header file kcadminc.h with which you can pass object properties and/or parameter values to UTM or get them from UTM. There are also corresponding data structures for some of the operations that do not form part of the standard operations. The data structures are described in section "Data structures used to pass information". The names of the data structures are created as follows:

The data structure "typ_str" belongs to the object or parameter type "TYP". For example, the data structure kc_user_str belongs to KC_USER, and kc_max_par_str to KC_MAX_PAR.

A similar principle applies to non-standard operations. E.g. the data structure kc_application_par_str belongs to the operation code KC_APPLICATION_PAR.

-->obj_number

Number of objects for which the required operation is to be carried out. In obj_number you specify the number of objects about which UTM is to supply information when information is requested (KC_GET_OBJECT).

<--number_ret

UTM returns the actual number of objects for which the operation was carried out in number_ret.

-->id_lth

In the id_lth field you must specify the length of the identification area identification_area passed in the call.
If no identification area is passed, then id_lth=0 must be specified.

-->select_lth

In the select_lth field you must specify the length of the data structure that is passed to UTM in the selection area selection_area.
If no selection area is passed, then select_lth=0 must be specified.

-->data_lth

In the data_lth field you must specify the length of the data area data_area passed in the call or in which UTM shall return data.
If no data will be passed in the data area, then data_lth=0 must be specified. 

<--data_lth_ret

UTM returns the actual length of the data returned in the data area in the data_lth_ret field. 

Identification area

The identification area identification_area is used to identify the target object for the administration operation. All objects within a group of a certain object type must be uniquely identified by their object_name.

The following union is provided for passing the object name using the identification area.

union kc_id_area

char kc_name2[2];

char kc_name4[4];

char kc_name8[8];

char kc_name32[32];

struct kc_triple_str triple;

struct kc_long_triple_str long_triple;

struct kc_ptc_id_str ptc_id;

Whether or not an object in the identification area needs to be uniquely specified depends on the function called.

The object name must be specified as follows in order to uniquely identify it:

• For the object types KC_CON an KC_PTERM, you must pass the triplet name, processorname and bcamappl-name as the object name to UTM using the union field long_triple of type kc_long_triple_str. Here name is the name of the object (for example the PTERM name), processor-name is the name of the computer on which the object is located, and bcamappl-name is the name of the local application via which the connection between the object and the application is established.

  struct  kc_long_triple_str

  char p_name[8];

  char pronam[64];

  char bcamappl[8];

• For the object type KC_MUX on BS2000 systems, you must pass the triplet name, processor-name and bcamappl-name as the object name to UTM using the union field triple of type kc_triple_str. Here name is the name of the object, processor-name is the name of the computer on which the object is located, and bcamappl-name is the name of the local application via which the connection between the object and the application is established.

  struct  kc_triple_str

  char p_name[8];

  char pronam[8];


  char bcamappl[8];

   

• For an LTERM pool (object type KC_TPOOL) you must pass the LTERM prefix, from which the names of the LTERM partners in the LTERM pool can be created, as the object name. The LTERM prefix must be passed to UTM using the kc_name8 union field.

• For the object type KC_TACCLASS you must pass the TAC class number as the object name using the kc_name2 union field if the function call applies to a particular TAC class. Otherwise specify binary 0 to indicate that the call applies to all TAC classes.

• For the object type KC_DB_INFO you must adopt the identification of the database (db_id) as the object name in the union element kc_name2 if the function call is to be valid for a particular database. db_id is a number and represents the databases in the order in which they were generated in the KDCDEF run.

• For load modules, shared objects, DLLs (object type KC_LOAD_MODULE) and program units (KC_PROGRAM), pass the name specified at generation using the kc_name32 union field.

• For the object type KC_SFUNC (UTM function keys) you must pass the short description of the function key as the object name in the union element kc_name4.

• For the function KC_PTC_TA (roll back a transaction in PTC state), you must fill the union element kc_ptc_id_str with the values from the structure ptc_ident. You can get the content of ptc_ident by first calling KC_GET_OBJECT with object type KC_PTC.

  The data structure kc_ptc_id_str is defined as follows:

  struct kc_ptc_id_str

  char vg_indx[10];

  char vg_nr[10];

  char ta_nr_in_vg[5];

• For the remaining object types, pass the object name specified at generation using the kc_name8 union field if the function call applies for a particular object. Otherwise specify binary 0 to indicate that the call applies to all objects of this type.

If the identification area is not supported for a call, then you must set the area address to the null pointer. You must then set id_lth=0 in the parameter area.

Selection area

In the selection area you can pass a data structure containing selection criteria to UTM when querying information (operation code KC_GET_OBJECT). UTM then returns only the names and properties of the objects of the specified object type which meet the selection criteria.
The selection criteria must be passed in the data structure defined in kcadminc.h for that object type (obj_type). In the data structure you must set the search values for the fields to be used for selection.

Example

You would like to query information on which user IDs are currently signed on as users or clients. To do this, you specify the value 'Y' in the connect_mode field in the data structure kc_user_str in the selection area. 

If several selection criteria are specified simultaneously, then only those objects meeting all of the selection criteria will be returned. The remaining fields in the structure must be set to binary zero. The selection criteria that can be used in a search can be found in the description of KC_GET_OBJECT starting from section "Selection area" in chapter "KC_GET_OBJECT - Query information".

If you want to pass selection criteria, then when calling KDCADMI, you must pass the address of the selection area and, in the select_lth field in the parameter area, specify the length of the data structure passed in the selection area.

If the selection area is not used for a call, then you must set the &selection_area area address to the null pointer. You must then set select_lth=0 in the parameter area.

Data area

The data area is used to pass object properties, parameter values and information to or from UTM. The structure of the data depends on the operation code and on the type of the target object.

If data is to be passed in the data area during a KDCADMI call, then you must pass the address of the data area and set the data_lth field of the parameter area to the length of the data structure passed in the data area.

If information is queried which is to be stored in the data area, then you must, when calling KDCADMI, pass the address of the data area you have provided to store the return data and set the data_lth field of the parameter area to the length of this data area.

If the data area is not used in a call, then you must pass the null pointer as the address of the area. You must then set data_lth=0 in the parameter area.

The data area must not exceed 16 MB.