The syntax of the UTM start parameters is illustrated below:
|
With the syntax shown 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 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 |
END | This command concludes the input of start parameters (openUTM, The start parameters must be specified in own blocks:
Each block is concluded with the END command. |
Meaning of the operands
| FILEBASE = filebase | ||||||||||||||||
Base name of the KDCFILE and the user log file. Here you must specify the name under which the KDCFILE is stored at startup time (with a maximum of 42 characters in length). If an invalid name is specified, the application start is aborted. | ||||||||||||||||
| ADMI-TRACE= | ||||||||||||||||
Enable/disable the ADMI trace function (= trace function for the KDCADMI For information on the names of the trace files, see "Trace files" (Start parameters for openUTM). | ||||||||||||||||
ON OFF | The ADMI trace function is enabled at the start of the application. The ADMI trace function remains disabled at the start of the application. Default: OFF | |||||||||||||||
| ASYNTASKS = number | ||||||||||||||||
Maximum number of tasks that are to work for asynchronous services. Default value: Number defined in MAX...,ASYNTASKS=number | ||||||||||||||||
| BTRACE = | ||||||||||||||||
Enable/disable the BCAM trace function. | ||||||||||||||||
| ON | The BCAM trace function is enabled at the start of the application. For further information on setting up the trace file and analyzing it using the utility program KDCBTRC and for a description of the trace, see the openUTM manual “Messages, Debugging and Diagnostics on BS2000 Systems” | |||||||||||||||
| 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 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 | |||||||||||||||
| CATID = (catalog-A,catalog-B) | ||||||||||||||||
With this parameter you can specify the catalog IDs to which the parts of the KDCFILE are assigned. If you are working with CATID, you must specify the base name without CATID in the FILEBASE parameter. In the case of dual-file operation, you can assign the files with suffix A to catalog-A and the files with suffix B to catalog-B. If you are working with dual-file operation and if you only specify catalog-A, both files will be assigned to the same CATID. | ||||||||||||||||
| CPIC-TRACE = | ||||||||||||||||
Enable/disable the CPI-C trace function (= trace function for the X/Open interface CPI-C), see also openUTM manual “Creating Applications with X/Open Interfaces”. For information on the names of the trace files, see "Trace files" (Start parameters for openUTM). | ||||||||||||||||
| 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 task is terminated. Default: 0 (no timeout)Minimum value: 60Maximum value: 3600 | ||||||||||||||||
| DBKEY = db-key | ||||||||||||||||
Key comprising up to eight characters for accessing the database. Only valid for UDS databases! db-key is used when calling the database system if no DBKEY is defined for the transaction code of the calling program unit. Default value: C’UTM ’ | ||||||||||||||||
| DUMP-CONTENT = | ||||||||||||||||
Specifies whether openUTM dumps the global task storage areas in all dumps of a dump file generation, i.e. for all tasks, or only in the dump of the task that caused the application crash. | ||||||||||||||||
STANDARD (STD) | If openUTM creates a dump file generation, global task storage areas are only contained in the dump of the first process (initiator). This is normally sufficient for diagnostic purposes. Default value: STANDARD | |||||||||||||||
EXTENDED (EXT) | The global task storage areas are contained in all dumps of a DUMP file generation. This value should only be set if explicitly requested by the system service. | |||||||||||||||
| DUMP-MESSAGE = (event-type, event) | ||||||||||||||||
Event for which UTM creates a UTM dump when test mode is enabled. A dump is only created by the task in which the event occurred; the application is not terminated. The following can be specified for event-type, event: event-type=MSG,event=Knnn (K message) The UTM dump is created when message Knnn occurs. A dump is only created once for message numbers K023, K043, K061, K062; thereafter, event is reset automatically.With all other messages, a dump is created each time the message number occurs until the value is reset by the administrator. The value of DUMP-MESSAGE can be reset by the administrator, e.g. using WinAdmin/WebAdmin or by issuing the command event-type =RCCC,event=rccc (compatible KDCS return code) Specify a KDCS return code (KCRCCC, e.g. 40Z) for rccc. When this return code is returned for a KDCS call, the process in which the return code occurred generates a UTM dump e.g. with dump code CC-40Z. The message dump for this event is then automatically deactivated. event-type=RCDC,event=rcdc (internal KDCS return code) Specify a KDCS return code (KCRCDC, e.g. KD10) for rcdc. When this return code is returned for a KDCS call, the process in which the return code occurred generates a UTM dump event-type=SIGN,event=sign (SIGN status code) Specify a SIGNON status code (KCRSIGN1/2, e.g. U05) for sign, where KCRSIGN1 must have the value U, I, A or R. If this code is issued when a user signs on, the process in which the SIGNON status occurred generates a UTM dump e.g. with dump code SG-U05. This happens irrespective of whether a signon service has been generated in the application or not. The message dump for this event is then automatically deactivated. Notes For all KDCS return codes >=70Z and the associated incompatible KDCS return codes for which no PENDER dump is written (e.g. 70Z/K316), no dump is created either. Up to three different events can be specified in the administration command KDCDIAG or by the corresponding function at WinAdmin/WebAdmin or KDCADMI 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. The dump code depends on the event:
| ||||||||||||||||
| DUMP-PREFIX | ||||||||||||||||
filename-prefix is the filename prefix for UTM dump files. It can be a maximum of 17 characters in length. If you specify filename-prefix, openUTM writes the memory dumps to a file generation group (FGG) or to a normal BS2000 file (dump file) with the name filename-prefix If you do not specify a filename-prefix or if the memory dump (without blanks) is written at a very early phase during startup of the application, openUTM writes the memory dumps to a file generation group or to a file with the name
| ||||||||||||||||
| DUMP-USERID = | ||||||||||||||||
Specifies the user ID under which the UTM dumps are to be stored. | ||||||||||||||||
STANDARD (STD) | The UTM dumps will be stored under the user ID that started the UTM task. Default: STANDARD | |||||||||||||||
SYSUSER (SYS) | The UTM dumps will be stored under the $SYSUSER user ID. | |||||||||||||||
| ENTER-PROC-INPUT = enter-proc-input | ||||||||||||||||
Specification of the ENTER-PROC file and its parameters. enter-proc-input may be a maximum of 255 characters in length. This parameter can be specified more than once. The specification must be enclosed in single quotation marks. The parameters specified in multiple ENTER-PROC statements are assembled in the order in which they are specified. The maximum length of the aggregate specifications is 2000 characters. If the maximum total length is exceeded, a message is output and the start of the application is aborted. The collected enter-proc-input parameters are issued by UTM by means of an ENTER-PROC command. They must consequently be specified in the correct syntax of the ENTER-PROC command. Example: .UTM START ENTER-PROC-INPUT='START-DYN-PROC,(PAR1=<par1>,PAR2=<par2>' .UTM START ENTER-PROC-INPUT=',PAR3=<par3>),LOGGING=*NO' This issues the following command:
In the event of syntax errors in this command, the message K048 is output, and no follow-on task is started. | ||||||||||||||||
OTRACE = | ||||||||||||||||
Enable/disable the OSS trace function. | ||||||||||||||||
| ON | Enables the OSS trace function on the start of the application.Trace records of types SPI, INT, OSS, SERV and PROT are logged. When the OSS trace function is switched on, each process of the application creates its own trace file. | |||||||||||||||
| (SPI,NT,OSS,SERV,PROT) | Enables 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 off when the application starts. Default: OFF | |||||||||||||||
| PASSWORD = connection-password | ||||||||||||||||
A 4-character password that must be specified by the user to establish a logical terminal connection to the application (see section "Standard sign-on processfor terminals"). Default value: No password (X’0000 0000’) | ||||||||||||||||
| ROOTNAME = rootname | ||||||||||||||||
The parameter is mandatory if the ROOT table module is to be loaded dynamically. rootname is the PLAM element name of the ROOT table module in the library specified with TABLIB=. | ||||||||||||||||
| STARTNAME = | ||||||||||||||||
The simultaneous specification of the ENTER-PROC-INPUT and STARTNAME parameters is rejected with the message K039. The start of the application is aborted. | ||||||||||||||||
| enterfile | Name of the file specified in the ENTER command. The ENTER file must be cataloged under the user ID under which the application was started. enterfile may be up to 54 bytes long. | |||||||||||||||
| enteroperand | Operand of the BS2000 command ENTER. openUTM starts the follow-up | |||||||||||||||
START-SSL-PROC = enter-ssl-proc-input | ||||||||||||||||
This parameter is only required if you have generated a BCAMAPPL with SECURE (see chapter Starting a UTM application Starting the Application with TLS Connections) Specifies your own START procedure for the SSL proxy and, if necessary, parameters for the ENTER PROCEDURE call, without the procedure parameters required to start the SSL proxy (these are automatically generated by UTM and specified when the procedure is called). Length: 255, the parameter can be specified several times, specified in single quotation marks, they are put together in the order in which they are specified. The maximum length of the collected data is 2000 characters. You should start the job for SSL proxy like the UTM tasks without CPU time limitation. For this reason, you should set CPU LIMIT=NO(or TIME=NTL) or define the job class accordingly. If the CPU time is limited, that is, CPU LIMIT is not set to NO, and a CPU time runout occurs for the job, the SSL proxy is terminated abnormally. Please note that an NTL authorization (NoTimeLimit) in the user entry for the relevant billing number may be required for the execution of enter tasks without a CPU time limit. Example: .UTM START START-SSL-PROC='OWN.START.SSL,JOB-NAME=ownnam,JOB-CLASS=jcbname' This sends the following command: ENTER-PROC OWN.START.SSL,JOB-NAME=ownnam,JOB-CLASS=jcbnam, PROC-PAR=(par1,par2,par3..5) -> this part is appended by UTM If syntax errors occur in this command, a K099 message appears and the application continues to start (but no SSL proxy is started). | ||||||||||||||||
| STXIT = | ||||||||||||||||
Enable/disable STXIT routines. | ||||||||||||||||
| ON | The UTM-STXIT is enabled on the start of the application. Default value: ON | |||||||||||||||
| OFF | The UTM-STXIT remains disabled. This is only possible for UTM applications started interactively. | |||||||||||||||
| STXIT-LOG = | ||||||||||||||||
Enable/disable of extended STXIT logging in the event of problems involving STXIT processing. Several K099 messages are output at SYSOUT. | ||||||||||||||||
| ON | The STXIT logging function is enabled at the start of the application. | |||||||||||||||
| OFF | The STXIT logging function remains diabled at the start of the application. Default: OFF | |||||||||||||||
| SYSPROT = | ||||||||||||||||
| Switch over system files SYSOUT and SYSLST | ||||||||||||||||
| interval | Switchover interval in days Default: 0 (no interval: the files are not switched over at a specified time interval, but only on request) | |||||||||||||||
filename-prefix | Prefix for the new file name of the system files that have been switched over. Default: You will find a complete description of how to switch over the system log files in the section "System files SYSOUT and SYSLST". | |||||||||||||||
| TABLIB = libname | ||||||||||||||||
The parameter is mandatory if the ROOT table module is to be loaded dynamically. The libname library must then contain the object of the ROOT table module. | ||||||||||||||||
| TASKS = number | ||||||||||||||||
Number of BS2000 tasks that are to be started for the application. Default value: Number defined in MAX...,TASKS=number Minimum value: 1 *) If the application is to work with several processes, then the STARTNAME= start parameter or the ENTER-PROC-INPUT start parameter must also be specified. *) If the application is generated with Program Wait (i.e. if either a TAC class or a TAC is generated with PGWT=YES) then a value of at least 2 must be specified for the TASKS start parameter. In addition to the number of tasks defined in TASKS, UTM starts further tasks for an application. These are known as UTM system tasks. The purpose of the UTM system task is to ensure that applications continue to be responsive even under high loads. The system tasks 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 tasks 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). Default value: Number defined in MAX ...,TASKS-IN-PGWT=number in the UTM generation. | ||||||||||||||||
| TESTMODE = | ||||||||||||||||
Enable/disable test mode. | ||||||||||||||||
| ON | Test mode is enabled when the application starts. In test mode, additional internal UTM plausibility checks are executed 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 system service. | |||||||||||||||
| OFF | Test mode is to remain disabled when the application starts. In particular situations, dumps are suppressed after PEND ER if TESTMODE=OFF. Default value: OFF | |||||||||||||||
| FILE | Test mode is enabled 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. The file name is made up of the base name filebase and the TSN of the respective task, i.e. the following file is created for each task for a UTM production application: filebase. | |||||||||||||||
| TX-TRACE = | ||||||||||||||||
Enable/disable the TX trace function (= trace function for the X/Open interface TX), see also openUTM manual “Creating Applications with X/Open Interfaces”. For information on the names of the trace files, see "Trace files" (Start parameters for openUTM). | ||||||||||||||||
| 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 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 TX interface trace function remains disabled at the start of the application. Default: OFF | |||||||||||||||
| UTM-MSG-DATE = | ||||||||||||||||
Specifies whether UTM messages are output to SYSOUT/SYSLST with or without date/time. | ||||||||||||||||
| YES | All UTM messages to SYSOUT/SYSLST are prefixed with the date/time. Default: YES | |||||||||||||||
| NO | The UTM messages do not include any date/time prefix. | |||||||||||||||
| XATMI-TRACE= | ||||||||||||||||
Enable/disable the XATMI trace function (= trace function for the X/Open interface XATMI), see also openUTM manual “Creating Applications with X/Open Interfaces”. For information on the names of the trace files, see "Trace files" (Start parameters for openUTM). | ||||||||||||||||
| 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 one of the following files:
KDC.TRC. trace-type.appliname.tsn
trace-type
Identifies the trace type:
ADMI
ADMI trace (link name: KDCADMI)
CPIC
CPI-C trace (link name: KDCCPIC)
TX
TX trace (link name: KDCTX)
XATMI
XATMI trace (link name: KDCXATMI)
appliname
Name of the application
tsn
TSN of the UTM task (4 digits)
You can also assign your own trace files via link names.