Update generation for standalone UTM applications

Steps

Before performing the operations below, please read section "Backing up data"!

Steps 1 to 5 on the following pages explain how to use the tool KDCUPD to update the KDCFILE.

1. Create the new KDCFILE with KDCDEF

2. Terminate the application normally

3. Rename/copy the old KDCFILE and back up the user log file

4. Call KDCUPD

5. Start application

These steps are described in detail on the following pages. The method shown here is only one of several possibilities. In all cases, you must ensure that the KDCFILE is not overwritten, see warning in section "Backing up data".

Figure 20: Updating the KDCFILE

1) Create the new KDCFILE with KDCDEF

You can change the configuration of your application in the KDCDEF run, i.e. you can define new partner applications and connections, for example, delete existing ones or change application properties, etc.

It is possible to switch from single-file to dual-file operation. In addition, the “new” KDCFILE can be divided into several files, or the number of files can be changed. When dual-file operation is used and/or the new KDCFILE is distributed across several files, all these files must exist and KDCUPD must be able to access them.

2) Terminate the application normally

Terminate the application normally, see "Prerequisite for using KDCUPD".

The application must be terminated normally before calling KDCUPD so that the old KDCFILE is in a consistent state.

Make sure that the user log file exists and is not locked when the application is terminated. openUTM stores the user log records (LPUT calls) temporarily and does not write them to the file immediately. When the application is terminated normally, an attempt is made to write these records to the current user log file. If this attempt fails, the records remain in the old KDCFILE.
KDCUPD does not transfer these LPUT records to the new KDCFILE. But KDCUPD indicates with a warning message (K314) that the data get lost.

3) Copy the KDCFILE and back up the user log file

After terminating the application, you must copy or rename the current KDCFILE, for instance to OLD.KDCA. Then you assign the ‘correct’ name to the new KDCFILE.

When dual-file operation is used and/or the current KDCFILE is distributed across several files, all these files must be copied or renamed using the same filebase name, and KDCUPD must be able to access them.

Back up any existing user log file, as this file is overwritten when the system is restarted after a KDCDEF or KDCUPD run.

4) Call KDCUPD

In a subsequent KDCUPD run, specify the base name of the copied KDCFILE (including the user ID on BS2000) in the control statement KDCFILE OLD= and specify the base name of the newly generated KDCFILE in the control statement KDCFILE NEW=.

BS2000 systems:

Before calling KDCUPD you must do the following:

• The library SYSLNK.UTM.070 must be set as the tasklib:

  /SET-TASKLIB LIBRARY=$userid.SYSLNK.UTM.070

  The library of the openUTM version with which the new KDCFILE was generated must be assigned.If no library or an incorrect library was assigned, the DLL outputs a corresponding message.

• Process switch 3 should be set to OFF:

  /MODIFY-JOB-SWITCHES OFF=3

KDCUPD is called as follows:

  /START-EXECUTABLE-PROGRAM FROM-FILE=*LIB-ELEM -
                (LIBRARY=$userid.SYSLNK.UTM.070.UTIL,ELEMENT-OR-SYMBOL=KDCUPD) 
  : 
  : KDCUPD control statements 
  :
  END

Alternatively, you can also call KDCUPD via the SDF command START-KDCUPD. This command is located in the SDF UTM application area. For more detailed information, see openUTM manual “Using UTM Applications on BS2000 Systems” section "Calling UTM tools".

KDCUPD reads control statements from SYSDTA. A description of the KDCUPD control statements can be found as of "Control statements for KDCUPD".

KDCUPD outputs the procedure for logging purposes to SYSLST and/or SYSOUT (see control statement LIST in section "LIST - control the runtime log").

Unix, Linux and Windows systems:

The subdirectory DUMP must exist in the base directory of the old KDCFILE (filebase1) as well as in the base directory of the new KDCFILE (filebase2) before KDCUPD is called. DUMP is used for diagnostic purposes.

You start KDCUPD on Unix and Linux systems from the shell. You must call KDCUPD in a DOS window on Windows systems. Enter the following command to do this:

Unix and Linux systems: utmpath /ex/kdcupd 1>upd.out

Windows systems: utmpath \ex\kdcupd 1>upd.out.txt

Note the following:

• You should always redirect the output to stdout to a file (upd.out or upd.out.txt in the examples above).

• You may not redirect stderr (command mode) because KDCUPD asks you to enter the control statements via stderr (e.g. the ‘∗‘ of the KDCUPD input mode is output to stderr).

KDCUPD reads the control statements from stdin. A description of the control statements for KDCUPD can be found in section "Control statements for KDCUPD".

KDCUPD outputs the procedure for logging purposes to stdout and/or stderr (see control statement LIST in section "LIST - control the runtime log").

5) Start the application

The base name (filebase2) of the new KDCFILE must be specified in the start parameter FILEBASE=. Modify your start procedure if you have assigned a new base name to the new KDCFILE when creating it.

If the data has been transferred to the new KDCFILE with KDCUPD and you restart the application, then every user can continue to work as if the application was terminated normally and then restarted.