The syntax of the UTM start parameters is illustrated below:
|
In the syntax above the parameters are specified in a line without a carriage return and are separated by commas.
The UTM start parameters in the START command can be specified over several lines. In this case, the START command must appear in each line before the operands.
Syntax check at the start of the application
If openUTM detects a syntax error in the start parameters, it outputs message K038, sets the corresponding value of the start parameter to its default value (if any) and starts the application.
The application cannot be started when there is a syntax error in the FILEBASE or the CLUSTER-FILEBASE parameter because there is no default value for this parameter.
Meaning of the commands
START | This command is used to specify the UTM start parameters required for a UTM application run. The application is started as soon as all start parameters have been entered. |
END | This command concludes the input of start parameters. |
Meaning of the operands
| FILEBASE=filebase | ||||||||||||||||
The base name for the KDCFILE and the user log file in standalone applications. Here you must specify the name under which the KDCFILE is stored at startup time. If an invalid name is specified, the application start is canceled. filebase may be a maximum of 29 characters in length, irrespective of whether the name is specified as fully or partially qualified. If you specify the start parameter FILEBASE, you must not specify the start parameter CLUSTER-FILEBASE. In the case of UTM cluster applications, use the start parameter CLUSTER-FILEBASE instead of FILEBASE. The base name of an individual node application is defined in the CLUSTER-NODE statement during UTM generation. | ||||||||||||||||
| CLUSTER-FILEBASE=cluster_filebase | ||||||||||||||||
If you want to start a UTM application as a node application of a UTM cluster application, you use this start parameter to specify the basename for the cluster files. Here you must specify the name under which the files that are global to the cluster are stored at the startup time. CLUSTER-FILEBASE applies locally to the node. If you specify an invalid name here, the application start is canceled. For information on what names are valid, refer to the openUTM manual “Generating Applications”. If you specify the start parameter CLUSTER-FILEBASE, you must not specify the start parameter FILEBASE. | ||||||||||||||||
| ADMI-TRACE= | ||||||||||||||||
Enables/disables the ADMI trace function (= trace function for the KDCADMI administration program interface), see also openUTM manual “Messages, Debugging and Diagnostics on Unix, Linux and Windows Systems”. In UTM cluster applications, ADMI-TRACE applies locally to the node. For information on the names of the trace files, see "Trace files". | ||||||||||||||||
| ON | The ADMI trace function is enabled at the start of the application. | |||||||||||||||
| OFF | The ADMI trace function remains disabled at the start of the application. Default: OFF | |||||||||||||||
| ASYNTASKS=number | ||||||||||||||||
Maximum number of work processes that are to work for asynchronous services. In UTM cluster applications, ASYNTASKS applies locally to the node. Default: the number specified in MAX...,ASYNTASKS=number. | ||||||||||||||||
BTRACE= | Enable/disable the BCAM trace function. In UTM cluster applications, BTRACE applies globally to the cluster. | |||||||||||||||
ON | The BCAM trace function is enabled at the start of the application. | |||||||||||||||
OFF | The BCAM trace function remains disabled at the start of the application. Default: OFF | |||||||||||||||
length | Specifies the maximum length of data recorded when the BCAM trace function is activated. If the data to be recorded is longer, the first length/2 characters and the last length/2 characters of the data are recorded. This length can only be specified in the start parameters. Default: 256 If you use the BCAM trace for the UPIC Capture function (see also section"Recording the UPIC conversation (UPIC Capture)") then it is advisable to use the maximum value. | |||||||||||||||
| CPIC-TRACE= | ||||||||||||||||
Enables/disables the CPI-C trace function (= trace function for the X/Open interface CPI-C), see also openUTM manual “Creating Applications with X/Open Interfaces”. In UTM cluster applications, CPIC-TRACE applies locally to the node. For information on the names of the trace files, see "Trace files". | ||||||||||||||||
TRACE | The CPI-C trace function is enabled with the level TRACE at the start of the application. The content of the input and output parameters is output for each CPI-C function call. Only the first 16 bytes are output from the data buffers. The return codes of the KDCS calls to which the CPI-C calls are mapped are output. | |||||||||||||||
BUFFER | The CPI-C trace function is enabled with the level BUFFER at the start of the application. This trace level includes the TRACE level. However, the data buffers are logged in their full length. | |||||||||||||||
DUMP | The CPI-C trace function is enabled with the level DUMP at the start of the application. This trace level includes the TRACE level and also writes diagnostic information to the trace file. | |||||||||||||||
ALL | The CPI-C trace function is enabled with the level ALL at the start of the application. This trace level includes the levels BUFFER, DUMP and TRACE. | |||||||||||||||
OFF | The CPI-C trace function remains disabled at the start of the application. Default: OFF | |||||||||||||||
| DB-CONNECT-TIME=sec | ||||||||||||||||
Maximum time in seconds the system waits to establish a connection to the database. If no connection is established to the database during this wait time, message K078 Is issued and the utmwork process is terminated. In UTM cluster applications, DB-CONNECT-TIME applies locally to the node. Default: 0 (no timeout) | ||||||||||||||||
| DUMP-CONTENT= | ||||||||||||||||
Specifies whether openUTM dumps the global process storage areas in all dumps of a dump file generation, i.e. for all processes, or only in the dump of the process that caused the application crash. In UTM cluster applications, DUMP-CONTENT applies locally to the node. | ||||||||||||||||
| STANDARD | ||||||||||||||||
If openUTM creates a dump file generation, global process storage areas are only contained in the dump of the first process (initiator). This is normally sufficient for diagnostic purposes. Default value: STANDARD | ||||||||||||||||
| EXTENDED | ||||||||||||||||
| The global process storage areas are contained in all dumps of a DUMP file generation. | ||||||||||||||||
This value should only be set if explicitly requested by the Service personnel. | ||||||||||||||||
| DUMP-MESSAGE= (event-type, event) | ||||||||||||||||
Event where UTM generates a UTM dump with identifier MSGDMP when test mode is enabled. A dump is only created by the process in which the event occurred; the application is not terminated in the process. In UTM cluster applications, DUMP-MESSAGE applies globally to the cluster. The dump code depends on the event:
| ||||||||||||||||
The following can be specified for event-type, event:
Notes: Up to three different events can be specified in the administration command KDCDIAG using the parameters DUMP-MESSAGE1, DUMP-MESSAGE2 and DUMP-MESSAGE3. In contrast, only one event can be specified using the start parameter DUMP-MESSAGE. In addition, no message inserts can be specified for event-type=MSG in the start parameter. By contrast, up to three inserts can be specified as additional conditions in the KDCDIAG command. | ||||||||||||||||
| NODE-TO-RECOVER=node-name | ||||||||||||||||
This parameter is only relevant for UTM cluster applications. node-name is the name of the node application for which a node recovery is to be performed. Node recovery should only be performed for an abnormally terminated node application if a normal node warm start is either not possible or cannot be performed quickly because the node computer has failed and no virtual host has been defined. As a result, a node recovery for a node application is only possible on a node computer on which the abnormally terminated node For information on the conditions that must be fulfilled in order to perform node recovery for UTM cluster applications as well as on the purpose and function of node recovery, see section "Node recovery". If a database system does not support node recovery then node recovery always terminates abnormally. Default: Blanks, i.e. normal application start. | ||||||||||||||||
| OTRACE= | ||||||||||||||||
Switches on/off the OSS trace function on the start of the application. In UTM cluster applications, OTRACE applies globally to the cluster. | ||||||||||||||||
ON | Switches on the OSS trace function. | |||||||||||||||
| (SPI, INT, OSS, SERV, PROT) | ||||||||||||||||
| Switches on the OSS trace function on the start of the application. Trace records of the specified type are logged. The trace records are specified in an arbitrary sequence. | ||||||||||||||||
SPI The XAP-TP system programming interface is logged. INT The internal processes in the XAP-TP module are logged. OSS The OSS calls are logged. SERV The internal OSS trace records of type O_TR_SERV are logged. PROT The internal OSS trace records of type O_TR_PROT are logged. | ||||||||||||||||
| OFF | The OSS trace function remains deactivated on the start of the application. Default: OFF | |||||||||||||||
RESET-PTC = | ||||||||||||||||
This parameter is only relevant for UTM cluster applications if a value other than blanks has been set for NODE-TO-RECOVER. RESET-PTC specifies whether transactions with the state PTC ("prepare to commit") are rolled back during node recovery. A transaction with the PTC state may contain locks on global UTM storage areas that apply globally throughout the cluster and may possibly impair the current UTM cluster application. Transactions with the PTC state cannot be committed on a node recovery because no connections are established to partner applications. If transactions remain in the PTC state then the node recovery terminates abnormally, i.e. no online import or KDCUPD with the KDCFILE of the failed node application is permitted and any locks on UTM storage areas that are effective throughout the cluster are retained. If you are able to tolerate possible data inconsistencies, repeat the node recovery with RESET-PTC=YES in the case of existing transactions in the PTC state. | ||||||||||||||||
YES NO | Transactions in PTC state are rolled back on node recovery. Transactions in PTC state are retained on node recovery. Default: NO | |||||||||||||||
| STXIT= | ||||||||||||||||
Activates signal handling in openUTM. In UTM cluster applications, STXIT applies locally to the node. | ||||||||||||||||
ON | Signal handling is activated in openUTM. With STXIT=ON, the functionality „User Signal Routine“ can also be used on Unix and Linux systems. Default value: ON | |||||||||||||||
OFF | Default error handling for signals remains deactivated. | |||||||||||||||
Unix and Linux systems:
| ||||||||||||||||
SYSPROT= | Switch over the system files stderr and stdout. | |||||||||||||||
| interval | Switchover interval in days. | |||||||||||||||
In UTM cluster applications, interval applies globally to the cluster. Default: 0 (no interval, files are switched over using administration facilities) Maximum value: 364 | ||||||||||||||||
| filename-prefix | ||||||||||||||||
Prefix for the new file name of the system files that have been switched over. The prefix can be a fully-qualified or partially-qualified part of the file name. In UTM cluster applications, filename-prefix applies locally to the node. Default: utmp Maximum length: 31 characters You will find a comprehensive description of switching over the system log files in the section "System files stderr and stdout". | ||||||||||||||||
| TASKS=number | ||||||||||||||||
Number of work processes that are to work for this application. In UTM cluster applications, TASKS-IN-PGWT applies locally to the node. Default value: Number defined in MAX...,TASKS=number *) If the application is generated with Program Wait (i.e. if either a TAC class or a TAC is generated with PGWT=YES), or if the application is generated as a UTM cluster application then a value of at least 2 must be specified for the TASKS start parameter. In addition to the number of work processes defined in TASKS, UTM starts further work processes for an application. These are known as UTM system processes. The UTM system processes are intended to ensure that applications continue to be responsive even when running under load. The UTM system processes only process selected jobs which are characterized first and foremost by short runtimes. When an application is started, UTM starts up to three additional UTM system processes for the application depending on the number of started tasks (TASKS= number). | ||||||||||||||||
| TASKS-IN-PGWT=number | ||||||||||||||||
Maximum number of processes that can simultaneously execute program units with blocking calls (e.g. the KDCS call PGWT) are permitted (PGWT= operand in the TAC and TACCLASS KDCDEF statements). In UTM cluster applications, TASKS-IN-PGWT applies locally to the node. Default value: Number defined in MAX ...,TASKS-IN-PGWT=number Minimum value: 1 if MAX...,TASKS-IN-PGWT > 0; otherwise 0. | ||||||||||||||||
| TESTMODE= Activate test mode. | ||||||||||||||||
See also the openUTM manual “Messages, Debugging and Diagnostics on Unix, Linux and Windows Systems”, chapter “Debugging and error diagnosis”. In UTM cluster applications, TESTMODE applies globally to the cluster. | ||||||||||||||||
| ON | Test mode is to be switched on when the application starts. In test mode, additional internal UTM plausibility checks are carried out, and trace information is logged in the internal trace area. Test mode should only be switched on to diagnose UTM errors on the recommendation of the systems analyst. | |||||||||||||||
With MAX...,IPCTRACE= (see openUTM manual “Generating Applications”, MAX statement), the number of trace information entries written with TESTMODE=ON can be specified in the KDCDEF generation. IPCTRACE should only be defined for diagnosing serious UTM errors on the recommendation of the systems analyst. | ||||||||||||||||
| OFF | Test mode is to remain deactivated when the application starts. Default value: OFF | |||||||||||||||
| FILE | Test mode is activated when the application starts. In addition, the diagnostic data is written to a file each time the internal trace area overflows so as to avoid any loss of diagnostic data. filebase.KTATRC.pid (pid max. 4-position) | |||||||||||||||
| TX-TRACE= | ||||||||||||||||
Enables/disables the TX trace function (= trace function for the X/Open interface TX), see also openUTM manual “Creating Applications with X/Open Interfaces”. In UTM cluster applications, TX-TRACE applies locally to the node. For information on the names of the trace files, see "Trace files". | ||||||||||||||||
| ERROR | The TX trace function is enabled with the level ERROR at the start of the application. Only errors are logged. | |||||||||||||||
| INTERFACE | The TX trace function is enabled with the level INTERFACE at the start of the application. The level INTERFACE includes the level ERROR, and all TX calls are also logged. | |||||||||||||||
| FULL | The TX trace function is enabled with the level FULL at the start of the application. The FULL level includes the INTERFACE level. All KDCS calls to which the TX calls are mapped are also logged. | |||||||||||||||
| DEBUG | The TX trace function is enabled with the level DEBUG at the start of the application. The level DEBUG includes the level FULL, and diagnostic information is also logged. | |||||||||||||||
| OFF | The XATMI interface trace function remains disabled at the start of the application. Default: OFF | |||||||||||||||
| XATMI-TRACE= | ||||||||||||||||
Enables/disables the XATMI trace function (= trace function for the X/Open interface XATMI), see also openUTM manual “Creating Applications with X/Open Interfaces”. In UTM cluster applications, XATMI-TRACE applies locally to the node. For information on the names of the trace files, see "Trace files". | ||||||||||||||||
| ERROR | The XATMI trace function is enabled with the level ERROR at the start of the application. Only errors are logged. | |||||||||||||||
| INTERFACE | The XATMI trace function is enabled with the level INTERFACE at the start of the application. The level INTERFACE includes the level ERROR, and all XATMI calls are also logged. | |||||||||||||||
| FULL | The XATMI trace function is enabled with the level FULL at the start of the application. The FULL level includes the INTERFACE level. All KDCS calls to which the XATMI calls are mapped are also logged. | |||||||||||||||
| DEBUG | The XATMI trace function is enabled with the level DEBUG at the start of the application. The level DEBUG includes the level FULL, and diagnostic information is also logged. | |||||||||||||||
| OFF | The XATMI interface trace function remains disabled at the start of the application. Default: OFF | |||||||||||||||
Trace files
By default, the trace records of the ADMI, CPI-C, TX, and XATMI trace function are written to the following files in the directory filebase:
KDC.TRC.trace-type.appliname.pid (standalone application) or
KDC.TRC.trace-type.appliname.nodename.pid (UTM cluster application)
trace-type
Identifies the trace type:
ADMI ADMI trace
CPIC CPI-C trace
TX TX trace
XATMI XATMI trace
appliname
Name of the application
nodename
Name of the node on which the node application is running
pid
PID of the process
Sample contents of a start parameter file of a standalone application
.UTM START FILEBASE=/home/utmsmp (Unix and Linux systems) .UTM START FILEBASE=C:\utmtest\utmsmp (Windows systems) .UTM START TASKS=2 .UTM START TASKS-IN-PGWT=1 .UTM START ASYNTASKS=1 .UTM START TESTMODE=OFF .UTM START BTRACE=OFF .UTM START ADMI-TRACE=ON .UTM START OTRACE=OFF .UTM START STXIT=ON .UTM END