KC_CREATE_OBJECT allows you to add the following objects dynamically to the application configuration:
transport connections to remote LU6.1 applications (KC_CON)
key sets (KC_KSET)
LU6.1 sessions (KC_LSES)
transaction codes by means of which service programs are started in partner applications (KC_LTAC)
an LTERM partner to connect clients and printers (KC_LTERM)
application program units and VORGANG exits (KC_PROGRAM)
clients and printers (KC_PTERM)
transaction codes and TAC queues (KC_TAC)
user IDs, including their queues (KC_USER)
openUTM on Windows systems does not support any printers.
Exactly one object can be created per KC_CREATE_OBJECT call. Within any given program unit, however, KC_CREATE_OBJECT can be called several times, i.e. several objects with the same type or with different object types can be created.
You will find more detailed information on dynamically adding objects to the configuration in chapter "Changing the configuration dynamically".
If an object which can be dynamically generated in a UTM cluster application (Unix, Linux and Windows systems) has to be deleted then you must always delete it using the administration functions. These objects cannot be deleted simply by means of a regeneration.
Requirements for dynamically adding an object
During KDCDEF generation of the UTM application, RESERVE was used to reserve spaces in the table for the object type; one of these spaces in the table is still empty. You can determine if there are still free spaces available in the table for the corresponding object type using KC_GET_OBJECT and the KC_DYN_PAR parameter type.
You can only add application program units and VORGANG exits dynamically if the application was generated with load modules (BS2000 systems) or shared objects/DLLs (Unix, Linux and Windows systems). The program unit or VORGANG exit must be created by a compiler for which a program unit has already been statically configured (PROGRAM statement) during the KDCDEF generation.
Only on BS2000 systems: For ILCS-capable compilers, it is sufficient to statically generate a program unit with COMP=ILCS.
Transaction codes for program units that use an X/Open program interface can only be added dynamically if at least one transaction code for an X/Open program unit was configured during the KDCDEF generation.
User IDs can only be configured dynamically if the application was generated with user IDs.
Note for BS2000 systems:
User IDs with ID cards or can only be added dynamically if space in the table was reserved explicitly for user IDs with ID cards during the KDCDEF generation, and if one of these table spaces is still free.
You can only dynamically enter user IDs with Kerberos authentication if table spaces for user IDs with Kerberos authentication have been reserved explicitly and if one of these spaces is still free.
The following must be observed when adding new objects / cluster
Certain rules must be observed when adding objects that are related to each other. These rules are described in chapter "Changing the configuration dynamically". The following are examples of objects that are related to each other:
transaction codes and the program units and VORGANG exits assigned to them
clients/printers and the associated LTERM partners and the connection user IDs or user IDs for the automatic KDCSIGN
key sets referenced by user IDs, LTERM partners and transaction codes
Procedure / period of validity / transaction management / cluster
The call is subject to transaction management. Until the transaction has been completed, a dynamically created object can only be accessed within the transaction itself. Applicationwide access is only possible after the transaction has been completed. In particular, the object can only be manipulated by means of administration functions after the transaction has been completed (this includes information queries). Within the same transaction, the object can only be accessed when adding additional objects that are related to it.
The call’s effects extend beyond the end of the current application run. This means that objects added dynamically are also part of the configuration for later application runs (as long as the objects are not deleted again).
The following applies in UTM cluster applications (Unix, Linux and Windows systems):
The call applies globally to the cluster, i.e. the objects are dynamically entered in the configuration in all the node applications.
Data to be supplied
Function of the call | Data to be entered in the | |||
parameter area 1 | identification area | selection | data area | |
Add transport connections to the remote LU6.1 application to the configuration | obj_type: | —— | —— | Data structure kc_con_str with the name and properties of the partner and the connection |
Add key set to the configuration | obj_type: | —— | —— | Data structure kc_kset_str with the name and properties of the key set |
Add LU6.1 session to the configuration | obj_type: | —— | —— | Data structure kc_lses_str with the name and properties of the partners involved |
Add transaction code by means of which service programs are started in partner applications to the configuration | obj_type: | —— | —— | Data structure kc_ltac_str with the name and properties of the LTAC and the partner |
Add an LTERM partner to the configuration | obj_type: | —— | —— | Data structure kc_lterm_str with the name and properties of the LTERM partner |
Add a program unit or VORGANG exit to the configuration | obj_type: | —— | —— | Data structure kc_program_str with the name and properties of the program unit or VORGANG exit |
Add a client/printer (PTERM) to the configuration | obj_type: | —— | —— | Data structure kc_pterm_str with the name and properties of the client/printer |
Add a transaction code | obj_type: | —— | —— | Data structure kc_tac_str with the name and properties of the transaction code or TAC queue |
Add a user ID (including queue) to the configuration | obj_type: | —— | —— | Data structure kc_user_str with the name and properties of the user ID and queue |
1 The operation code KC_CREATE_OBJECT must be specified in the parameter area in all cases.
Parameter settings | |
Parameter area | |
Field name | Contents |
version | KC_ADMI_VERSION_1 |
retcode | KC_RC_NIL |
version_data | KC_VERSION_DATA_11 |
opcode | KC_CREATE_OBJECT |
Object type | |
1 | |
id_lth | 0 |
select_lth | 0 |
Length of the data in the data area | |
Identification area | |
— | |
Selection area | |
— | |
Data structure of the object type | |
KDCADMI call |
KDCADMI (¶meter_area, NULL, NULL, &data_area) |
Data returned by UTM | |
Parameter area | |
Field name | Contents |
Return codes | |
obj_type
In the obj_type field you must specify the type of object to be created. You can specify the following object types:
KC_CON, KC_KSET, KC_LSES, KC_LTAC, KC_LTERM, KC_PROGRAM, KC_PTERM, KC_TAC, KC_USER.
obj_number
Only one object can be created per call. Therefore you must set obj_number = 1.
data_lth
In the data_lth field you specify the length of the data structure you are passing to UTM in the data area.
Data area
You must pass a data structure in the data area containing the name of the new object and the properties to be assigned to this object. A unique data structure is provided for each individual object type, and you must place this data structure in the data area.
The tables on the following pages as of "obj_type=KC_CON" contain descriptions of the data structures as a function of the type of the object to be created. The table shows you which fields in the relevant data structure must be supplied with data.
The entries in the first column of the table have the following meanings:
o | Supplying the field with data is optional |
m | Supplying the field with data is mandatory |
(m) | Supplying the field with data may be mandatory, depending on the data you have entered for the other mandatory parameters or at the level of the operating system under which the UTM application is running. |
Fields in the data structures that you have not explicitly specified must be set to binary zero. UTM will use the default values for these fields. You can find the default values listed in the descriptions of the data structures in section "Data structures used to pass information".
retcode
In the retcode field UTM outputs the return codes of the call, see "Returncodes".