Data structures used to pass information

The data structures that you must place in the data area when calling KC_GET_OBJECT, KC_MODIFY_OBJECT or KC_CREATE_OBJECT are described in this section.

• For KC_GET_OBJECT UTM returns the object properties, application parameters and statistical data queried in the format of these data structures. The data structures are defined in the kcadminc.h header file.

• The data are passed to UTM in this format when changing object properties and application parameters (KC_MODIFY_OBJECT) and when dynamically adding new objects to the configuration (KC_CREATE_OBJECT).

The following two sections describe the data structures and the meanings of their constituent elements.
The section "Data structures for describing object properties" describes the structures used to pass information about objects of the application.
The section "Data structures used to describe the application parameters" describes the structures used to pass application parameters.

There are other data structures that do not belong to any object or parameter type in addition to those described in these sections. You will need these for certain calls to pass data to UTM. These data structures are covered in the descriptions of the corresponding operation codes.

Their names are created as follows: operationscode_str.

The following data structures belong to this group:

• You need kc_change_application_str when passing data for a program exchange with KC_CHANGE_APPLICATION ("KC_CHANGE_APPLICATION- Exchange application program").

• You need kc_create_statements_str to pass data to UTM when requesting an inverse KDCDEF run with KC_CREATE_STATEMENTS ("KC_CREATE_STATEMENTS - Create KDCDEF control statements (inverse KDCDEF)").

• You need kc_encrypt_advanced_str or kc_encrypt_str to read the public key of an RSA key pair with KC_ENCRYPT ("KC_ENCRYPT - Create, delete, read RSA key pairs").

• You need kc_shutdown_str to pass data to UTM when requesting a shutdown with KC_SHUTDOWN ("KC_SHUTDOWN - Terminate the application run").

• You need kc_syslog_str when administering the SYSLOG file with KC_SYSLOG ("KC_SYSLOG - Administer the system log file").

• You need kc_online_import_str to import application data online with KC_ONLINE_IMPORT.

• You need kc_lock_mgmt_str to release locks in UTM cluster applications using KC_LOCK_MGMT.

General information on the structure of the data structures

The fields in the data structures are not all of the data type "char”. The square brackets following the name of the field contain the length of the field. If there are no square brackets, then the field is 1 byte long.

The following points must be observed when exchanging data between UTM and an administration program unit:

• Names and keywords are left-justified and are padded to the right with blanks. The data passed to UTM must be in uppercase letters, except for object names.

  Example
  The ptype (kc_pterm_str) field is 8 bytes long. ptype =APPLI is stored as follows: 'APPLIbbb' (b = blank).

• Numeric data is stored right-justified by UTM and is returned with leading blanks. When data is passed from an administration program to UTM, left- and right-justified data is accepted. Right-justified data is accepted with leading blanks or zeros. Left-justified data can also be terminated by the null byte (\0) or padded with blanks.

  Example
  The conn_users (kc_max_par_str) field is 10 bytes long. conn_users =155 is stored by UTM as follows: 'bbbbbbb155' (b = blank).

• When passing data to UTM, fields in the data structures in which no values are specified are to be supplied with binary zero.

Description format

The data structures in kcadminc.h are presented in tables. The tables have the following structure:

mod	Data structure kc_..._str	Page
1.	2.	3.

1. The first column (shaded gray) specifies which parameters, i.e. field contents, you can modify with KC_MODIFY_OBJECT. If the "mod" column does not contain data, then you cannot modify any parameters.

   The abbreviations used in the first column have the following meanings:

   -	The parameter cannot be modified.
   x(y)	The value of the parameter can be modified.
   	The value in brackets (y) informs you of how long the modification is effective and in which way. y can take on one of the following values: IR/GIR, ID/GID, PR/GPR, PD/GPD, P/GP, A/GA. See chapter "KC_MODIFY_OBJECT - Modify object properties and application parameters" for the meaning of the abbreviations.

2. The second column contains the fields of the data structure as they are defined in kcadminc.h.

3. The third column is only used for presenting very large data structures. This column lists the page where you can find the description corresponding to the data structure field.

The meanings of the contents of the fields are described at the end of each table.