KC_MODIFY_OBJECT allows you to modify application parameters and object properties and perform other operations on application objects. You can make the following modifications:
Actions for the application’s objects
establish or shut down connections to clients, printers, partner applications
initiate automatic connections to clients, printers, partner applications
disable and enable clients, printers, partner applications, user IDs, including their queues, transaction codes and TAC queues
modify the assignment between client/printer and LTERM partner
modify the password for a user ID
change keys in key sets
alter the timer for monitoring idle states during a session, or deactivate monitoring
activate or deactivate the UTM BCAM trace for specific objects and users
replace an application program’s load modules or shared objects / DLLs
Exchange the master LTERMs of two LTERM bundles or add the LTERM to an LTERM group
Specify that queued messages are to be stored in the dead letter queue (TAC queue KDCDLETQ)
mark load modules on BS2000 systems which are loaded in common memory pools for exchange with KC_CHANGE_APPLICATION
modify the maximum number of clients on BS2000 systems that can be connected concurrently to the application through a multiplex connection
modify the computer name and filebase name of a node application
modify the database user ID and password
Actions for the application parameters
change the application timers
reset the statistics data
modify maximum values for the application
activate and deactivate diagnostic functions (e.g. BCAM trace)
define the number of processes (TASKS) that are to run for the application
set the maximum number of processes that asynchronous jobs or services with blocking function calls (e.g. KDCS call PGWT) can process concurrently.
modify the timers for the reciprocal monitoring of the node applications
in UTM cluster applications, reset the statistics values for the utilization of the cluster page pool
Passing new object properties and application parameter values
Data structures for passing new object properties or application parameters are available in the header file kcadminc.h. Each object type and each parameter type has its own data structure. The name of the data structure matches that of the object type/parameter type (in lowercase) with the suffix “_str“ (objecttyp_str, parametertyp_str). The following description specifies the fields to which you must pass the new properties. You will find a complete description of the data structures in section "Data structures used to pass information".
The following points should be noted when modifying object properties or application program parameters
When modifying object properties, you can only modify the properties of one object with one KC_MODIFY_OBJECT call.
You must specify the full object name in the identification area so that UTM can unambiguously identify the object.
Object names cannot be modified.
When modifying application parameters, you can modify all parameters belonging to the same parameter type, i.e. which are contained in a single data structure, within a single call.
The transactional modifications specified in a KC_MODIFY_OBJECT call are either made in their entirety or not at all. This does not apply for changes which are not subject to transaction management.
Period of validity / transaction management / cluster
The time at which a modification takes effect and the period for which it is applicable depend on the type of modification. The type of modification also determines whether or not it is subject to transaction management.
The following applies in a UTM cluster application (Unix, Linux and Windows systems):
The call can initiate actions which either have an effect either globally in the cluster or locally in the node. Actions with a global effect apply to all the node applications in the UTM cluster application irrespective of whether they are currently active or not. Actions with a local effect only apply to the node applications at which they are performed. Depending on the object, all its parameters apply either globally or locally or have a mixed global/local effect. The change may continue to apply beyond the current application run or may apply only to the current run. Modifications which have an impact on the UTM configuration always apply globally to the cluster to ensure that the generation remains consistent. Global validity is indicated by a "G" in the KC_MODIFY_OBJECT operation code column. If no "G" is present in the ID then the effect in a UTM cluster application is local to the node.
A detailed description of the scope of validity of the individual parameters of each object can be found in the description of the data structures.
The following types of modification may occur:
IR/GIR
The modification is not subject to transaction management. It takes effect immediately (Immediate), and applies only to the current application/UTM cluster application run (Run). A RSET call issued in the same transaction but after the modification rolls back the modification.
ID/GID
The modification is not subject to transaction management. It takes effect immediately (Immediate) and, regardless of the generation version (UTM-S or UTM-F), it applies beyond the current application/UTM cluster application run (Durable). A RSET call issued in the same transaction but after the modification rolls back the modification.
PR/GPR
The modification is subject to transaction management. It takes effect after the end of transaction (PEND) and it applies only to the current application/UTM cluster application run (Run). It can be rolled back with a RSET call issued in the same transaction.
P/GP
The modification is subject to transaction management. It takes effect after the end of transaction (PEND) and its duration depends on the generation version of the application. In the case of UTM-F, it only applies to the current application run, with UTM-S, however, it goes beyond the current application run. It can be rolled back within the same transaction with a RSET call.
PD/GPD
The modification is subject to transaction management. It takes effect after the end of transaction (PEND) and, independent of the generation version, its effect goes beyond the current application/UTM cluster application run (Durable). It can be rolled back within the same transaction with a RSET call.
A/GA
This generates an announcement (Announcement), which causes the desired modification (e.g. establishment of a connection/disconnection or exchange of application program) . When the job is executed depends on the load on the application. You can only tell whether the job was executed successfully or not in an information query issued later (e.g. using KC_GET_OBJECT). The job cannot be rolled back.
Note on period of validity in UTM cluster applications (Unix, Linux and Windows systems):
If the modification cannot be generated then the administrative modification continues to apply even when a node application is started with a new generation, but persists no later than the end of the UTM cluster application run. The UTM cluster application run begins with the start of the first node application and terminates with the end of the last node application.
If the modification can be generated, then the generation value and not the administratively modified value applies when a node application is started with a new generation.
The description of the possible modifications under section "Data area" tells you to which modification type the various modifications belong. The abbreviations listed above are used.
 | You can also perform some of the modifications using the administration commands. The description under section "Data area" identifies the commands concerned. |
Data to be supplied
Function of the call | Data to be entered in the | |||
parameter area1 | identification area | selection area | data area | |
Modification of object properties | obj_type: | Name of object | —— | Data structure of the object type with the new values of the properties |
Modification of application parameters | obj_type: | —— | —— | Data structure of the parameter type with the new parameter values |
1 The operation code KC_MODIFY_OBJECT must always be specified in the parameter area.
Parameter settings | |
Parameter area | |
Field name | Contents |
version | KC_ADMI_VERSION_1 |
retcode | KC_RC_NIL |
version_data | KC_VERSION_DATA_11 |
opcode | KC_MODIFY_OBJECT |
KC_NO_SUBOPCODE / KC_IMMEDIATE / KC_DELAY | |
Object type / parameter type | |
1 / 0 | |
Length of object name in identification area / 0 | |
select_lth | 0 |
Length of data structure in data area | |
Object name / — | |
Selection area | |
— | |
Data structure of object type or parameter type / — | |
KDCADMI call |
KDCADMI (¶meter_area, &identification_area, NULL, &data_area) or |
Data returned by UTM | |
Parameter area | |
Field name | Content |
Return codes | |
subopcode1
With obj_type = KC_DB_INFO you must specify KC_IMMEDIATE in the subopcode1 field if the change to the database password is to take effect immediately. With KC_DELAY the change to the database password only takes effect the next time the application is started. A change to the database user name only ever takes effect the next time the application is started.
For all other values of obj_type you must specify KC_NO_SUBOPCODE in subopcode1.
obj_type
In the obj_type field you specify the type of object whose properties are to be modified or the type of application parameters which are to be modified. The following modifications are permissible:
Object types
KC_CLUSTER_NODE
(only possible in a UTM cluster application)
Specify if you want to modify the computer names and/or filebase names of a node application.
You must, for example, specify KC_CLUSTER_NODE if you want to assign actual values for the computer name of the node and the base name of the node application’s KDCFILE to a reserve node application (see openUTM manual “Generating Applications” and openUTM manual “Using UTM Applications”).KC_DB_INFO
Specify if you want to change the database password and/or the database user name for a XA database.KC_KSET
Specify if you want to change keys in a key set.KC_LOAD_MODULE
Specify if you want to replace load modules of a UTM application on BS2000 systems or shared objects/DLLs of a UTM application on a Unix, Linux or a Windows system, i.e. if you want to load another version of a load module/shared object/DLL.KC_LPAP
Specify if you want to perform an operation for an LPAP partner of the application, i.e. if you want to modify the logical properties of an LU6.1 partner application.KC_LSES
Specify if you want to modify the properties of a session with an LU6.1 partner application.KC_LTAC
Specify if you want to modify the local properties of a remote service, i.e. the properties of an LTAC.KC_LTERM
Specify if you want to modify the properties of an LTERM partner.KC_MUX (only on BS2000 systems)
Specify if you want to modify the properties of a multiplex connection.KC_OSI_CON
Specify if you want to modify the properties of the connections to an OSI TP partner application.KC_OSI_LPAP
Specify if you want to perform an operation for an OSI-LPAP partner, i.e. you want to modify the logical properties of an OSI TP partner application.KC_PTERM
Specify if you want to perform operations for terminals, printers, client applications or TS applications.KC_TAC
Specify if you want to modify the properties of a transaction code which is assigned to a local service or a TAC queue.KC_TACCLASS
Specify if you want to modify the maximum number of processes that can process jobs concurrently for a certain TAC class.KC_TPOOL
Specify if you want to modify the properties of the LTERM partner or the number of active LTERM partners of an LTERM pool.KC_USER
Specify if you want to modify the properties of a user ID or its queue.
Parameter types
KC_CLUSTER_CURR_PAR
Specify if you want to reset the statistics values of the cluster page pool in a UTM cluster application.KC_CLUSTER_PAR
Specify if, for a UTM cluster application, you want tomodify the parameters which control the way the individual node applications interact to check their availability.
modify the parameters which control node application accesses to the cluster configuration file and the cluster administration journal.
KC_CURR_PAR
Specify if you want to reset application-specific statistical values.KC_DIAG_AND_ACCOUNT_PAR
Specify if you want to activate or deactivate diagnostic functions or if you want to modify the UTM accounting settings.KC_MAX_PAR
Specify if you want to modify maximum values for applications (the MAX parameter) or, in UTM(BS2000) applications, if you want to activate or deactivate the supply of data to openSM2.KC_TASKS_PAR
Specify if you want to modify values relating to the number of application processes, i.e. the total number of processes, maximum number of processes for executing asynchronous jobs etc.KC_TIMER_PAR
Specify if you want to modify timer settings.
Point Data area describes which modifications are possible for each object type and parameter type.
obj_number
What you have to specify in the obj_number field is determined by what is entered in the obj_type field:
specify obj_number=1 when you specify an object type in obj_type (exception: KC_TACCLASS, see below).
specify obj_number=0 when you specify a parameter type in obj_type or if you want to reset values in obj_type = KC_TACCLASS for all TAC classes.
id_lth
What you have to specify in the id_lth field is determined by what is specified in the obj_type field:
if you specify an object type in obj_type, you must specify the length of the data structure in id_lth which you pass to UTM in the identification area.
Exception: If obj_type = KC_DB_INFO and KC_TACCLASS you must specify id_lth=2.if you specify a parameter type in obj_type, you must set id_lth=0.
data_lth
In the data_lth field you specify the length of the data structure which you are passing to UTM in the data area.
data_lth=0 is not permitted.
Identification area
In the identification area you pass to UTM the name of the object whose properties you want to modify. This means that:
If you specify an object type in obj_type, then, in the identification area, you must pass the complete name of the object to UTM.
exceptions.
If obj_type = KC_TACCLASS and you reset values for all TAC classes then you must enter binary 0.
With obj_type = KC_DB_INFO you must specify a number to identify a database. This number represents the databases in the order in which they were generated in the KDCDEF run and are returned on the administration interface for KC_GET_OBJECT.
Section 7 specifies for each object type the information you must state in the identification area.
If you specify a parameter type in obj_type, then you do not need to pass any identification area to UTM. UTM ignores any information specified in the identification area.
Data area
In the data area you pass the data structure of the object or parameter type specified in obj_type. Each individual object or parameter type has its own data structure, which you must assign via the data area. You must pass the new property or parameter values to UTM in the data structure. You must complete the remaining fields of the data structure, i.e. the property or parameter value fields, which you do not wish to or cannot modify with binary zero before the call.
In openUTM on Unix or Linux systems, it is not always necessary to pass data in the data area for obj_type = KC_LOAD_MODULE since, when transferring shared objects without any version specification, the name of the shared object in the identification area is sufficient.
The following tables as of "obj_type=KC_CLUSTER_NODE" describe the modifications that are permitted as a function of object type/parameter type. You will be able to see from the description which properties/parameters you are able to modify and how the fields are to be completed. All the data structures are described in section "Data structures used to pass information".
retcode
UTM writes the return code for the call to the retcode field, see "Return codes".