You can generate the KDCFILE and the ROOT table sources in a single KDCDEF run or in separate KDCDEF runs. The KDCDEF statement OPTION allows you to define the generation objects to be created by KDCDEF:
OPTION...,GEN={ KDCFILE | ROOTSRC | NO | ALL }
|
For UTM cluster applications on Unix, Linux and Windows systems, there is the additional option CLUSTER, see "OPTION - manage the KDCDEF run".
The name of the ROOT tables is defined using the ROOT statement.
On BS2000 systems rootname is the name of the ROOT table module.
On Unix, Linux and Windows systems rootname is a name component of the ROOT table source (ROOTSRC).
KDCDEF reads the control statements from standard input or from a file.
On BS2000 systems standard input means SYSDTA (with the SDF command ASSIGN-SYSDTA you can assign SYSDTA to a SAM or ISAM file, a library member of type S, a PLAM library, or *SYSCMD, for example)
On Unix, Linux and Windows systems standard input means stdin (i.e. from the Unix or Windows command level).
You will find a detailed description of how to start KDCDEF and pass the control statements to KDCDEF in section "Calling KDCDEF and entering the control statements".
All KDCDEF statements are subjected to syntax and plausibility checks. If KDCDEF does not detect any serious errors in this process, the files listed in figure 2 are created for a standalone UTM application.
Figure 17 in chapter "UTM cluster files" shows what files are created when you generate a UTM cluster application.
The following figure shows what files are created when you define a standalone UTM application.
Figure 2: The result of the KDCDEF run (with OPTION ...,GEN=ALL) for a standalone UTM application.
KDCDEF statements for a minimal configuration
You must pass at least the following control statements to KDCDEF before you can run your UTM application.
You must execute additional KDCDEF statements for distributed processing, connecting specific clients and printers, etc. You will find more information on this subject in the sections "Generating applications for distributed processing", "Connecting clients to the application" and "Generating printers (on BS2000, Unix and Linux systems)".
The lines beginning with ’*’ are comments.
Minimal configuration for BS2000 systems:
****************************************************************************
*
* Specify which part of the application program is to be created
by KDCDEF
*
****************************************************************************
*
OPTION GEN=...
|
****************************************************************************
*
* Specify the name of the Root table
*
****************************************************************************
*
ROOT applroot
|
****************************************************************************
*
* Specify application parameters
*
****************************************************************************
*
* Application name with which communication partners
* can address the application
MAX APPLINAME= sample
* Specify the base directory of the application.
MAX KDCFILE= filebase
*
Define the maximum number of process of the UTM application
MAX TASKS=2
|
****************************************************************************
*
* optional: Generate the database system (ORACLE in the example)
*
****************************************************************************
*
DATABASE TYPE=XA
|
****************************************************************************
*
* optional: Specify the formatting system used
*
****************************************************************************
*
* the statement FORMSYS must only be specified if your UTM application
* is to run in formatted mode
FORMSYS TYPE=FHS
|
****************************************************************************
*
* Connection points (LTERM partners) for clients/TS applications
*
****************************************************************************
*
* For example, generate open LTERM pools so that clients/TS applications
* can connect to the application
* LTERM pools for the various types of client ------------------------------ (1)
TPOOL LTERM= client, NUMBER=..., PTYPE=*ANY, PRONAM=*ANY
BCAMAPPL upicappl, T-PROT=ISO
TPOOL LTERM= upic, NUMBER=..., PTYPE=UPIC-R, BCAMAPPL= upicappl, PRONAM=*ANY
TPOOL LTERM= appli, NUMBER=..., PTYPE=APPLI, PRONAM=*ANY
BCAMAPPL sockappl, T-PROT=SOCKET, LISTENER-PORT=number
TPOOL LTERM= socket, NUMBER=..., PTYPE=SOCKET, BCAMAPPL=sockappl, PRONAM=*ANY
|
****************************************************************************
*
* Generate services
*
****************************************************************************
*
* Some own program units that initiate services and generate the
* corresponding transaction codes
* (for COMP=... enter the compiler used or the runtime system, mostly „ILCS“,)
PROGRAM= userpu ,COMP=...
TAC usertc ,PROGRAM= userpu. ...-------------------------------------------- (2)
|
****************************************************************************
*
* Administration
*
****************************************************************************
*
* Administration program KDCADM
PROGRAM KDCADM,COMP=ILCS )
* Generate administration command KDCSHUT so that the application
* can always be terminated normally
TAC KDCSHUT,PROGRAM=KDCADM ... --------------------------------------------- (3)
* In applications with user IDs:
* user ID for the administrator
USER admin ,PERMIT=ADMIN,PASS=....
* If administration will be done via WinAdmin/WebAdmin,
* then you need to submit the following TAC and PROGRAM statements
* and generate a connection for the UPIC client (an LTERM pool in this case)
* Furthermore, you should then generate the admin user ID with administration
* authorization and without the restart property or generate your own
* user ID with administration authorization and without the restart property
* for administration using WinAdmin/WebAdmin.
* Administration program KDCWADMI
PROGRAM KDCWADMI,COMP=..
TAC KDCWADMI,PROGRAM=KDCWADMI,CALL=BOTH,ADMIN=Y
TPOOL LTERM=WADM,PTYPE=UPIC-R, PRONAM=*ANY, NUMBER=1 ------------------------(5)
|
****************************************************************************
*
*optional: Reserve space in the table for dynamic administration
*
****************************************************************************
*
RESERVE OBJECT=...,NUMBER=... ---------------------------------------------- (4)
END
|
Remarks |
(1) | For each of the client types (terminal, UPIC client, TS application) that are to connect to the application, you must generate a separate LTERM pool. For terminals, a single LTERM pool is sufficient - depending on the type of terminals that are to sign in to the application. You can also generate the LTERM pools so that all clients of a particular type can log in - regardless of the computer on which they are located. You can also implement client connections with the help of the LTERM/PTERM statements. In particular, you must use LTERM/PTERM statements if the UTM application itself establishes connections to clients (e.g. TS applications) or if a printer is to be generated. For UPIC clients, HTTP clients and TS socket applications a separate BCAMAPPL statement with T-PROT=ISO or (SOCKET, ...) is required. |
(2) | You can also assign several transaction codes to a program unit if the program unit performs several different services. |
(3) | You can generate all administration commands that you will want to use in operation using additional TAC statements. If you want to use your own administration programs for administration purposes, then you must generate these programs with the corresponding PROGRAM and TAC statements. |
(4) | You can add additional objects to the application configuration during live operation with the help of the administration (see the openUTM manual “Administering Applications”). You will need to create space in the tables in the KDCFILE for these objects in the KDCDEF generation. |
(5) | The connection for a WinAdmin or WebAdmin client can also be generated with PTERM-/LTERM statements instead of with a TPOOL statement - e.g. with a privileged LTERM, see openUTM manual “Administering Applications”. |
Minimal configuration for Unix, Linux and Windows systems
****************************************************************************
*
* Specify which part of the application program is to be created
by KDCDEF
*
****************************************************************************
*
OPTION GEN=...
|
****************************************************************************
*
* Specify the name of the Root table
*
****************************************************************************
*
ROOT applroot
|
****************************************************************************
*
* Specify application parameters
*
****************************************************************************
*
* Application name with which communication partners
* can address the application
MAX APPLINAME= sample
* Specify the base directory of the application.
* This directory is the directory in which the KDCFILE is stored,
* amongst other things.
MAX KDCFILE= filebase
* Specify the key for the shared memory area
MAX CACHESHMKEY=..,IPCSHMKEY=...,KAASHMKEY=...
[,OSISHMKEY=...,XAPTPSHMKEY=...] --------------------------- (1)
Define the semaphore key for the global application semaphore
MAX SEMARRAY= number , number1
* Define the maximum number of process of the UTM application.
MAX TASKS=2
|
****************************************************************************
*
* optional: Generate the database system (in the example ORACLE)
*
****************************************************************************
*
RMXA XASWITCH=xaoswd,SPEC=C
|
****************************************************************************
*
* Connection points (LTERM partners) for clients/TS applications
*
****************************************************************************
*
* For example, generate open LTERM pools so that clients/TS applications
* can connect to the application
* LTERM pools for the various client types --------------------------------- (2)
TPOOL LTERM=clientr, PTYPE=UPIC-R, NUMBER=...
TPOOL LTERM=clientl, PTYPE=UPIC-L, NUMBER=...
TPOOL LTERM=appli, PTYPE=APPLI, NUMBER=...
BCAMAPPL aockappl, T-PROT=SOCKET, LISTENER-PORT=number
TPOOL LTERM=socket, PTYPE=SOCKET, BCAMAPPL=sockappl, NUMBER=...
TPOOL LTERM=term, PTYPE=TTY, NUMBER=...
|
****************************************************************************
*
* Generate services
*
****************************************************************************
*
* Some own program units that initiate services and generate the
* corresponding transaction codes (for COMP=... enter the compiler used)
PROGRAM= userpu ,COMP=...
TAC usertc ,PROGRAM= userpu. ...-------------------------------------------- (3)
|
****************************************************************************
*
* Administration
*
****************************************************************************
*
* Administration program KDCADM
PROGRAM KDCADM,COMP=C
* Generate administration command KDCSHUT so that the application
* can always be terminated normally
TAC KDCSHUT,PROGRAM=KDCADM ...---------------------------------------------- (4)
* In applications with user IDs: user ID for the administrator
USER admin ,PERMIT=ADMIN,PASS=....
* If administration will be done via WinAdmin/WebAdmin,
* then you need to submit the following TAC and PROGRAM statements
* and generate a connection for the UPIC client (an LTERM pool in this case)
* Administration program KDCWADMI
PROGRAM KDCWADMI,COMP=C
TAC KDCWADMI,PROGRAM=KDCWADMI,CALL=BOTH,ADMIN=Y
TPOOL LTERM=WADM,PTYPE=UPIC-R, NUMBER=1 ------------------------------------
(6)
|
****************************************************************************
*
* optional: Reserve space in the table for dynamic administration
*
****************************************************************************
*
RESERVE OBJECT=...,NUMBER=... ---------------------------------------------- (5)
END
|
Remarks |
(1) | You only need to specify the shared memory key OSISHMKEY= and XAPTPSHMKEY=
if you generate objects for communication via OSI TP. The other shared memory areas are needed by every UTM application, running on Unix, Linux or Windows systems. |
(2) | On Unix, Linux or Windows systems you must generate a separate LTERM pool for each type of client (terminal, UPIC client, TS application) that is to be able to connect to the application. You can generate the LTERM pools so that all clients of a particular type are able to sign on - regardless of the computer on which they are located. You can also configure client connections using the LTERM/PTERM statements. In particular, you must use LTERM/PTERM statements if the UTM application itself establishes connections to clients (e.g. TS applications) or if a printer is to be generated on Unix or Linux systems. For HTTP clients and TS socket applications a separate BCAMAPPL staement with T-PROT=(SOCKET, ..) is required. |
(3) | You can also assign several transaction codes to a program unit if the program unit performs several different services. |
(4) | You can generate all administration commands that you will want to use in operation using additional TAC statements. If you want to use your own administration programs for administration purposes, then you must generate these programs with the corresponding PROGRAM and TAC statements. |
(5) | You can add additional objects to the application configuration during live operation with the help of the administration (see the openUTM manual “Administering Applications”). You will need to create space in the tables in the KDCFILE for these objects in the KDCDEF generation. |
(6) | The connection for a WinAdmin or WebAdmin client can also be generated with PTERM-/LTERM statements instead of with a TPOOL statement - e.g. with a privileged LTERM, see openUTM manual “Administering Applications”. |
Regenerating existing UTM applications
If you want to generate a new ROOT table source and/or a new KDCFILE for an existing application (i.e. KDCROOT and KDCFILE already exist), then you must note the following:
You must enter the information on objects that are entered dynamically in the KDCFILE during operation or whose properties have been changed in the new KDCFILE. The “inverse KDCDEF“ function is provided for this purpose. With this function you create the control statements from the configuration information of the current KDCFILE that can be used immediately. You will need to call the CREATE-CONTROL-STATEMENTS control statement in the KDCDEF run in order to do this.
Via the UTM administration you can also execute the inverse KDCDEF run while the application is running.
| You will find more information on the “inverse KDCDEF“ function in section "Inverse KDCDEF". |
Figure 3: KDCDEF run with inverse KDCDEF
