Starting a UTM application on Unix and Linux systems with the debugger

If you want to debug a program unit that executes automatically when the application is started, e.g. program units for a Start-Exit or the MSGTAC program for start messages then you must start the application in a special way:

1. Start the utmmain process as a background process as with a UTM production application. However, you must also specify the TEST parameter.

   utmpath /ex/utmmain filebase startparam-file TEST &

   You must always specify the start parameter file as a fully qualified file name even if the default name is used.

   The main process utmmain then creates only the timer process and additional resources such as the pipe used to communicate with the work process. No work processes are created, however.

2. The main process requests you to start one or more work processes via message U244. Please note that if you are testing in dialog mode then the second work process is a UTM system process and that it may therefore be necessary to start three work processes if, for example, programs are to be tested with PGWT.

   You must start the first work process, utmwork, under the control of the debugging aids with the following arguments:

   utmwork version appliname filebase startpar pid id mode

   The entire statement must be entered without a carriage return, even if you need more than one line. The arguments have the following meanings:

   version appliname filebase startpar pid	openUTM version used, e.g. V07.0A23 Name of the application as generated in MAX APPLINAME. Directory in which the application program is stored (fully qualified). File in which the start parameters are defined (fully qualified). Process ID of the predecessor process for PEND ER or a value of 0 for additional processes.
   id	ID of the utmwork process. On the start of the first and an additional work process (Mode=Y or N), you must always specify the value 0. If Mode=E then the value from the corresponding U244 message must always be specified.
   mode	Code for the start mode Y: First work process of the application N: Additional new work process E: Restarted after PEND ER

   Example for dbx

   run V07.0A23 sample /home/utmbsp /home/utmbsp/startparameter 0 0 Y

   You can take the parameters for starting the work processes from the associated message U244.

3. You should always restart work processes when the main process requests you to do so with message U244.

   Additional processes always require the value N as the last argument.

   utmwork version appliname filebase startpar pid id N

   Example for dbx

   run V07.0A23 sample /home/utmbsp /home/utmbsp/startparameter pid id N

   You cannot start more work processes than were specified in the start parameter file in TASKS= . The maximum number of work processes is defined in the UTM generation in the MAX statement. If you attempt to start more work processes, start errors will occur.

4. After the UTM application has terminated, you must use the kill command to delete the main process, if not all the work processes have fully completed process termination processing.

   Example

   kill -9 utmmain

   where 1234 is the process ID of utmmain.

You will find a detailed description of the steps to be taken to start the application in the openUTM manual “Using UTM Applications on Unix, Linux and Windows Systems”.

Behavior in the event of errors

If a work process creates a PEND ER dump, this work process is terminated and outputs a U244 message. The main process does not then start a new work process. You must then restart the work process manually and specify E as the last parameter. The exact parameters can be taken from message U244 of the terminated work process. As pid, specify the process ID of the preceding work process that terminated with PEND ER.

utmwork version appliname filebase startpar pid id E

If a work process is terminated incorrectly, you should call the UTM tool KDCREM before the next application start. See also the corresponding section in the openUTM manual “Using UTM Applications on Unix, Linux and Windows Systems”.

Terminating the application

As usual, you terminate the application using UTM administration functions or using the UTM tool KDCSHUT. If the application is not terminated normally, you should call the UTM tool KDCREM.

For further details, see the corresponding sections on KDCSHUT and KDCREM in openUTM manual “Using UTM Applications on Unix, Linux and Windows Systems”.