KC_CREATE_STATEMENTS allows you to start an inverse KDCDEF run during the application run (online). The inverse KDCDEF creates KDCDEF control statements from the configuration data. In this way, all changes resulting from dynamically adding, modify and deleting objects can be carried over to a new generation.
The KDCDEF control statements created by the inverse KDCDEF represent a consistent state of the configuration of the running application in the following sense:
The changes to the configuration data carried out by a transaction are always taken fully into account by an inverse KDCDEF running simultaneously.
See also the section on inverse KDCDEF runs in the openUTM manual “Generating Applications”.
The inverse KDCDEF allows you to create the following KDCDEF control statements:
CON statements for transport connections to remote LU6.1 applications
KSET statements for all key sets
LSES statements for all LU6.1 sessions
LTAC statements for transaction codes by means of which service programs are started in partner applications.
LTERM statements for all LTERM partners that do not belong to an LTERM pool or a multiplex connection
PTERM statements for all clients and printers that have been explicitly added to the configuration
PROGRAM statements for all program units and VORGANG exits
TAC statements for all transaction codes and TAQ queues in the application
USER statements for all user IDs including their queues
The inverse KDCDEF creates a control statement for each object of the specified type that is contained in the configuration, irrespective of whether these objects were loaded dynamically or not and whether their properties have been modified or not. The inverse KDCDEF does not create control statements for objects deleted with KC_DELETE_OBJECT.
You can find detailed information on the inverse KDCDEF in chapter "Generating konfiguration statements from the KDCFILE".
Controlling the inverse KDCDEF run
The inverse KDCDEF differentiates between the following seven object groups
First group | LTERM partners, clients, printers (object types: KC_LTERM, KC_PTERM) |
Second group | program units, transaction codes, TAC queues |
Third group | user IDs (object type: KC_USER) |
Fourth group | key sets (object type: KC_KSET) |
Fifth group | transaction codes via which the service programs are started in partner applications (object type: KC_LTAC) |
Sixth group | transport connections to LU6.1 applications |
Seventh group | LU6.1 sessions (object type: KC_LSES) |
You can use the KC_CREATE_STATEMENTS call to create KDCDEF control statements for objects of one or more of these groups.
You must specify the file in which UTM is to write the KDCDEF control statements in the KC_CREATE_STATEMENTS call. You can have all control statements written into one file or you can specify a file for each of the object groups. You may also specify in the call whether UTM is to create a new file or append the data to an existing file.
On BS2000 systems, the control statements can also be written to an LMS library element instead of a file. The procedure for library elements is similar to the procedure for files.
Execution of an inverse KDCDEF run
The time at which the inverse KDCDEF run is started and execution itself are dependent on the current state of the application. The following two cases can occur:
The inverse KDCDEF run is started asynchronously if transactions that have write access to the configuration data of the objects are running at the time of the KC_CREATE_STATEMENTS call. The inverse KDCDEF run is only started after these transactions have been completed. In the case of new transactions that are intended to change data in the object tables, the corresponding calls to change the configuration data of the application are rejected until the inverse KDCDEF run is completed (i.e. until the asynchronous job is processed).
The following also applies in UTM cluster applications (Unix, Linux and Windows systems):
In all running node applications, an administration action which applies globally to the cluster results in this type of transaction which may delay the start on the inverse KDCDEF. Conversely, the execution of a global administration action at a running node may be delayed if an inverse KDCDEF is currently running there.The inverse KDCDEF run is started synchronously if no transactions that have write access to the configuration data of the objects are running at the time of the KC_CREATE_STATEMENTS call. The run is already finished when control returns to the administration program. This means that, at this point in time, all of the KDCDEF control statements requested have been created and written to the files specified.
Results of the inverse KDCDEF runs
After a successful inverse KDCDEF run, the control statements requested are stored in the files specified in the call. These files can be used as input for the UTM generation tool KDCDEF when regenerating the application. You must pass each of the files to KDCDEF with the KDCDEF control statement OPTION DATA=filename. The files can be edited and modified.
The same applies if the control statements on BS2000 systems are written to LMS library elements instead of to files. However, whether or not elements can be edited depends on their type: only text-type elements can be modified.
Transaction management / cluster
The KC_CREATE_STATEMENTS call only reads the data in the KDCFILE. For this reason, the call is not subject to transaction management. The call cannot be undone in the same transaction using an RSET call.
The following applies in UTM cluster applications (Unix, Linux and Windows systems):
The call applies locally to the node, i.e. an inverse KDCDEF run for the generation of control statements from the configuration data is only started in this node application. It is sufficient for the effect to be local to the node since the same objects exist in every node application. An effect global to the cluster would simply generate identical KDCDEF statements.
If node applications with different generations are running (during an online update), then the call is rejected since the result would otherwise depend on the application at which the call was executed.
Data to be supplied
Function of the call | Data to be entered in the | |||
parameter area | identification area | selection area | data area | |
Create KDCDEF control statements online | Operation code: STATEMENTS | —— | —— | Data structure with information on the type of control statements to be created as well as the names and write modes of the files |
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_STATEMENTS |
id_lth | 0 |
select_lth | 0 |
Length of data in the data area | |
Identification area | |
— | |
Selection area | |
— | |
Data structure kc_create_statements_str | |
KDCADMI call |
KDCADMI (¶meter_area, NULL, NULL, &data_area) |
Data returned by UTM | |
Parameter area | |
Field name | Contents |
Return codes | |
data_lth
In data_lth you specify the length of the data structure kc_create_statements_str.
Data area
In the data area you must specify whether or not UTM is to create the KDCDEF control statements for each of the object groups. If UTM is to create control statements for an object group, you must also specify the file in which UTM is to write the control statements and the write mode of the file. The header file kcadminc.h contains the following data structure definition for passing information to UTM.
Definition of constants
#define KC_FILE_NAME_LTH 54 #define KC_ELEM_NAME_LTH 64 #define KC_VERSION_LTH 24 #define KC_TYPE_LTH 8
Definition of the index constant
typedef enum
{ KC_DEVICE_STMT = 0,
KC_PROGRAM_STMT = 1,
KC_USER_STMT = 2,
KC_KSET_STMT = 3,
KC_LTAC_STMT = 4,
KC_CON_STMT = 5,
KC_LSES_STMT = 6,
KC_MAX_STMT_TYPE = 6,
KC_DUMMY_STMT_TYPE = 7
} KC_INVDEF_TYPE;
Definition of the data structure
struct kc_create_statements_str
{ struct
{ char create_control_stmts;
char file_name[KC_FILE_NAME_LTH];
char file_mode;
char lib_name[KC_FILE_NAME_LTH];
char elem_name[KC_ELEM_NAME_LTH];
char vers[KC_VERSION_LTH];
char type[KC_TYPE_LTH];
} type_list[(int)KC_MAX_STMT_TYPE + 1];
char stmt_type;
char file_error_code[4];
};
The KC_INVDEF_TYPE index of the type_list array specifies the group to which the objects belong:
KC_DEVICE_STMT
stands for the first group, consisting of the LTERM partners, clients and printers. The KDCDEF control statements LTERM and PTERM are created in this group.
KC_PROGRAM_STMT
stands for the second group, consisting of the program units, transaction codes and TAC queues. The KDCDEF control statements PROGAM and TAC are created in this group.
KC_USER_STMT
stands for the third group, consisting of the UTM user IDs. The KDCDEF USER control statements are created in this group.
KC_KSET_STMT
Stands for the 4th group, the KSETs. The KDCDEF control statements KSET are generated in this group.
KC_LTAC_STMT
stands for the 5th group, the transaction codes by means of which service programs are started in partner applications. The KDCDEF LTAC control statements are created in this group.
KC_CON_STMT
Stands for the 4th group, the transport connections to LU6.1 applications. The KDCDEF control statements CON are generated in this group.
KC_LSES_STMT
stands for the 7th group, the LU6.1 sessions. The KDCDEF LSES control statements are created in this group.
The fields in the data structures must be supplied with the following data:
create_control_stmts | ||
You specify here whether or not KDCDEF control statements are to be created for the object group belonging to KC_INVDEF_TYPE. | ||
'Y' | KDCDEF control statements are to be created for this object group. | |
'N' | No KDCDEF control statements are to be created for this object group. You can also specify the null byte ('\0') in place of the 'N'. | |
file_name | The name of the file in which the KDCDEF control statements are to be written. The name may be up to 54 characters long. It must conform to the file naming conventions of the operating system under which the application is running. On Unix, Linux and Windows systems, the file name can be specified as an absolute or relative path name. A relative file name specification will write the KDCDEF control statements to a file in the directory in which the application was started. | |
file_mode | Write mode of the file in file_name bor of the element in elem_name | |
'C' | Create: On BS2000 systems, inverse KDCDEF generates an SAM file or an LMS library element. Here, the following applies:
| |
'E' | Extend:
| |
lib_name (only on BS2000 systems) | ||
Name of the LMS library in which the KDCDEF control statements are to be stored. The name can be up to 54 characters in length. It must comply with the conventions for file names on the BS2000 system. If the name is shorter than the field length then it must be padded with spaces. It is not permissible to specify file_name and lib_name at the same time. If lib_name is specified then it is also necessary to enter values for elem_name, vers and type. | ||
elem_name (only on BS2000 systems) | ||
Name of the LMS library element to which the KDCDEF control statements are to be written. The name can be up to 64 characters in length. If the name is shorter than the field length then it must be padded with spaces. The name must comply with the conventions for LMS element names | ||
vers (only on BS2000 systems) | ||
Version of the LMS library element to which the KDCDEF control statements are to be written. The version can be up to 24 characters in length and must comply with the conventions for LMS version specifications. If the version is shorter than the field length then it must be padded with spaces. You can also enter the following character strings as the version: | ||
*HIGHEST-EXISTING | ||
The statements are written to the highest version of the specified element present in the library. | ||
*UPPER-LIMIT | ||
The statements are written to the highest version of the specified element present in the library. | ||
*UPPER-LIMIT | ||
The statements are written to the highest possible version of the specified element. LMS indicates this version by means of an "@". | ||
*INCREMENT | ||
A new version is created for the specified element. *INCREMENT may only be specified if file_mode='C'. These character strings may not be truncated! | ||
type (only on BS2000 systems) | ||
Type of the LMS library element to which the KDCDEF control statements are to be written. The type can be up to 8 characters in length and must comply with the conventions for LMS type specifications. If the type is shorter than the field length then it must be padded with spaces. It is recommended to use the LMS type "S" for type. | ||
KDCDEF does not check whether the specifications in elem_name, vers or type comply with the LMS syntax rules. For further information on the syntax rules for the names of LMS elements and a specification of version and type, see the manual "LMS SDF Format". | ||
stmt_type | If a value other than KC_MC_OK is returned as the main code then the field stmt_type contains the index from KC_INVDEF_TYPE, to which the error message refers. | |
file_error_code | ||
If the subcode KC_SC_FILE_ERROR is returned when an error occurs then the field file_error_code contains the DMS error code or (on BS2000 systems) the associated PLAM error code. | ||
The type_list array is processed in order starting with the first array element (index KC_DEVICE_STMT) and proceeding to the last array element (index KC_LSES_STMT) when UTM is called. If UTM is to create KDCDEF control statements for all three object groups, then the create_control_stmts field must be set to 'Y', the file_name field must be set to the file name and the file_mode field must be set to the write mode of the file in each array element. If all of the control statements are to be written to one file, then you should ensure that the correct write mode has been set. You can set the write mode to 'C' or 'E' for the first entry of the file or the LMS library element. In the following array elements, however, the write mode must be set to 'E'. Otherwise, the control statements just created will be overwritten. If UTM is not to create control statements for one of the object groups, then create_control_stmts='N' (or nothing at all) is to be specified in the corresponding array element. | ||
retcode
In the retcode field UTM outputs the return codes of the call. In addition to the codes listed in section "Return codes", the following return codes can also arise:
Main code = KC_MC_OK The call was processed without errors. Subcode: |
KC_SC_ASYN_INIT The job was accepted; the inverse KDCDEF will be started asynchronously as soon as all transactions that modify configuration data have terminated. |
Main code = KC_MC_DATA_INVALID Invalid or missing data in the data area. Subcodes: |
KC_SC_DATA_MISSING No data was specified in the data structure passed in the data area. |
KC_SC_NO_INFO Invalid data was specified in the data structure passed in the data area. |
KC_SC_FILE_LIBRARY_MISMATCH (only on BS2000 systems) Both a file name (file_name) and an LMS library (lib_name) have been specified. |
KC_SC_LMS_ELEMENT_MISSING (only on BS2000 systems) An LMS library (lib_name) was specified but no element name (elem_name). |
KC_SC_LMS_VERSION_MISSING (only on BS2000 systems) An LMS library (lib_name) was specified but no element version (vers). |
KC_SC_LMS_TYPE_MISSING (only on BS2000 systems) An LMS library (lib_name) was specified but no element type (type). |
KC_SC_LMS_VERSION_MODE_MISMATCH (only on BS2000 systems) *INCREMENT was specified as LMS version but file_mode is not 'C'. |
Main code = KC_MC_MEMORY_INSUFF There is not enough internal UTM memory available. Subcode: |
KC_SC_NO_INFO |
Main code = KC_MC_REJECTED_CURR The call cannot be processed at the present time. Subcode: |
KC_SC_INVDEF_RUNNING An inverse KDCDEF is currently running or an inverse KDCDEF run is being prepared asynchronously, i.e. the job cannot be processed at the present time. |
Main code = KC_MC_REJECTED The call was rejected by UTM. Subcodes: |
KC_SC_NOT_GEN KDCDEF control statements are to be generated for objects whose types were not generated, such as USER commands for an application without user IDs. |
KC_SC_FILE_ERROR One of the files in which the KDCDEF control statements are to be written cannot be written to. A DMS error code or (on BS2000 systems) a PLAM error code is returned in the field file_error_code. This code provides ingormation about the error that has occurred |
KC_SC_NO_INFO The page pool used to temporarily store the parameters passed is full. |
KC_SC_CLUSTER_CONF_INCONS Only for UTM cluster applications: |