Starting a UTM application

A UTM application can be started as an ENTER process from the BS2000 console or from any terminal.

The CPU time etc. for the application is calculated under the BS2000 user ID used for this purpose.

All the necessary files must be cataloged either under this ID or under another ID on the same host with SHARE=YES.

The following files are required:

• library with a start LLM

• KDCFILE

• user log file (USLOG, optional)

• system log file (SYSLOG)

• user files of the application

• module library SYSLNK.UTM.070

• library with the connection module for the database system (optional)

• library with the connection module for the format handling system (optional)

• library with the formats (optional)

The ENTER or procedure file for starting the UTM application contains:

• CREATE-FILE- and SET-FILE-LINK commands for the system log file

• CREATE-FILE- and SET-FILE-LINK commands for user files (optional)

• START-EXECUTABLE-PROGRAM command for calling the application program

• Start parameters for UTM, FHS or the database system

When an ENTER file has been created, the application is started by calling the BS2000 command ENTER-JOB:

/ENTER-JOB FROM-FILE=enterfile[,JOB-CLASS=job-class]

          [,RESOURCES=PARAMETERS(CPU-LIMIT=tttt)]

In the case of a procedure file, use the BS2000 command ENTER-PROCEDURE to start the application:

/ENTER-PROCEDURE FROM-FILE=enter-proc-file (with the same parameters)

Recommendations for the selection of the parameters:

• You should set up a separate job class in which you set the most important parameters for the ENTER job of a UTM application.

  You can assign the job class then in the ENTER-PROC command or in the ENTER-JOB command (or concerning the parameters in an ENTER-JOB file in the SET-LOGON-PARAMETERS command).

• The operand CPU-LIMIT (CPU time limit) should be specified in the ENTER-PROC command or in the ENTER-JOB command if it is not specified in the SET-LOGON-PARAMETERS command in the ENTER-JOB file.

  The value should be set such that the jobs of a UTM application are not subject to any CPU time restriction. For this reason, you should set CPU-LIMIT=NO (or TIME=NTL) or define the job class accordingly.

  If the CPU time is limited, i.e. if CPU-LIMIT not equal NO has been set, and a CPU time runout occurs for a task of the application, then this can lead to the abnormal termination of the UTM application!

  Please note that an NTL authorization (No Time Limit) may be necessary in the user entry for the corresponding account number so that the Enter process can run without a CPU time limit.

  You can set CPU utilization limits for individual program units of a UTM application in the KDCDEF generation in the TIME operand of the TAC statement.

All the requirements for operating the application are fulfilled when the UTM application starts, i.e. the areas and tables are created, files are opened, connections are established, etc. These actions may result in error situations, which are identified by the start routine and which may lead to the termination of the application start or of a task. openUTM then outputs UTM message K078 or K049 to SYSOUT, which indicates the reason for the termination (see also the openUTM manual “Messages, Debugging and Diagnostics on BS2000 Systems”).

In the start procedure, no commands need be issued to check the consistency of the files opened by openUTM (REPAIR-DISK-FILES or CHECK-FILE-CONSISTENCY); openUTM automatically calls these commands when opening files that were not closed correctly.

The application program remains loaded until it is terminated either by the interception of the administrator or as a consequence of an error. The manner in which openUTM terminates the application program is important for the structure of the start procedure by the user.

The following situations can occur:

• On a normal termination using the administrative tools (e.g. via WinAdmin/WebAdmin or the administration command KDCSHUT NORMAL/WARN/GRACE) or after the application has terminated (Term Application abnormally), openUTM terminates the application program with TERM UNIT=STEP, i.e. all commands up to the next /SET-JOB-STEP or up to /EXIT-JOB or /LOGOFF are ignored in the ENTER procedure.

• When exchanging the application program with KDCAPPL PROG=NEW or following a program error which results in PEND ER, the application program should be loaded dynamically and restarted. openUTM then terminates the program with TERM UNIT=PRGR, i.e. the next command of the ENTER procedure is interpreted. This should be a /SKIP-COMMANDS command, which leads back to the
  /START-EXECUTABLE-PROGRAM command for starting the application program.

The processing in the start procedure following the /SET-JOB-STEP command can be rendered dependent on whether the UTM application was terminated normally or abnormally:

If the application is terminated abnormally (Term Application), openUTM creates an entry with LINK-NAME=KDCTRMAP in the task file table (TFT). In the start procedure, you can query (with /SHOW-FILE-LINK) whether such an entry exists in the TFT and control the subsequent procedure accordingly. When a UTM dump is written, the LINK name KDCDUMP is assigned for this purpose. In the start procedures, the user can execute the UTM-Tool KDCDUMP immediately to analyze the dump, for example.

The monitoring with job variables offers another means of restarting openUTM after an abnormal termination (see section "Restarting after an abnormal application termination").

The start procedure is described in the following sections. It is contained in a file named enterfile or enter-proc-file in this section.

With the start procedure you create an ENTER process. The user ID used must be specified in the ENTER-JOB or ENTER-PROC command or in the SET-LOGON-PARAMETERS command of the start procedure.

UTM processes that are started by ENTER-JOB or ENTER-PROC are batch processes. They are thus subject to the JOB-CLASS restrictions for batch tasks. Normally, however, you want to start UTM processes immediately. This can be achieved using the “JOB EXPRESS” function. In this case, you must specify START-IMMEDIATE=YES in the user entry of the BS2000 user ID under which the processes are to run.

In addition to the batch and dialog tasks, there is also the class of TP processes on BS2000 systems. This is handled as a priority by the operating system. The processes started with ENTER-JOB or ENTER-PROC are registered by openUTM as TP processes. However, these processes are only handled as a priority if TP processes are permitted under the respective BS2000 user ID or job class. If TP processes are prohibited, UTM processes run as batch processes.

All the processes of an application must be started under the same BS2000 user ID.

•   A UTM application can also be started interactively. This should only be done for test purposes, see also openUTM manual “Messages, Debugging and Diagnostics on BS2000 Systems”.
•   The start procedure can also be started using WinAdmin/WebAdmin. For this purpose, the openFT product must also be installed in addition to WinAdmin/WebAdmin (on BS2000 systems and on the WinAdmin or WebAdmin computer).

For an example of a start procedure, refer to the section "Basic structure of an SDF start procedure"