The asynchronous commands can be called by:
terminal users
TS applications
LU6.1 or OSI TP partner applications
other dialog or asynchronous program units in the application
The users/(OSI-)LPAPs that call the commands must have administration authorization.
When an asynchronous command is submitted, an asynchronous job is generated which openUTM adds to the message queue of the relevant administration TACs of KDCADM. The job is then executed independently of the job-submitting service or program unit.
The asynchronous commands make “programmed or automatic administration” possible. The data supplied by the standard administration program KDCADM can be passed to another program unit which analyzes the data and initiates appropriate actions (calling additional commands or transaction codes). The asynchronous commands can, for example, be called by event service MSGTAC which responds to certain events (UTM messages) when an administration command is called.
Submitting administration commands
At a terminal, asynchronous commands must be entered in line mode, as they are with administration in dialog mode. Partner applications pass commands together with operands to the application. The same operands are passed as in dialog mode. The asynchronous commands differ from dialog commands only in terms of their name.
A KDCS program unit calls an asynchronous command, either by submitting an FPUT NE call or, if the command is to be executed by a certain time, by submitting a DPUT NE call.
You supply the name of the asynchronous command (=transaction code) to the KDCS parameter field KCRN of the call. The message area for the call must contain the operand list of the administration command. You must pass every administration command in an FPUT or DPUT call.
You can send several calls relating to the same administration command and which are to be processed in one transaction as message sections. Every message section must contain an administration command (including the operands). The administration program KDCADM reads the message sections in a loop of FGET calls and processes them.
| First call of the administration command, e.g. KDCLTRMA |
| Second call from KDCLTRMA |
| Further calls from KDCLTRMA |
| Last call from KDCLTRMA |
The user ID under which the program unit is running must have administration privileges. The MSGTAC program unit always has administration privileges (see also the description of the MSGTAC program unit in the openUTM manual „Programming Applications with KDCS”).
Output of the result
After the job has been processed, openUTM informs you of the result via an asynchronous message. This message has the following format:
Header
1st line of result (= 1st line on screen, as for dialog output)
2nd line of result (= 2nd line on screen, as for dialog output)
:
:
The result is output with the same number of lines as the corresponding dialog command. Only the line output in dialog mode for the scrolling function is omitted.
The structure of screen lines for dialog output is illustrated in chapter "Administration commands - KDCADM" beside the description of the appropriate command.
Structure of header
ADMCMD: | Command Name | blank | Operands in the administration command |
8 bytes | 8 bytes | 1 byte | ... variable ... |
Recipient for the result
All messages generated by the asynchronous commands go to the same recipient (DESTADM) which can be defined either during KDCDEF generation or at runtime by administration using either WinAdmin, WebAdmin or the KDCADMI program interface (opcode=KC_MODIFY_OBJECT and object_type=KC_MAX_PAR, see "obj_type=KC_MAX_PAR"). Administration can define a different recipient at any time. A recipient can take the form of an asynchronous TAC which further processes the result or the LTERM partner of a terminal, printer or a TS application.
If no recipient has been defined, openUTM still carries out the administration commands but the result messages are lost in the process.
However, if an asynchronous TAC is defined as the recipient, and if it is not available, e.g. because it is disabled, the command is not executed and openUTM generates the message K076.
If the recipient is an LTERM partner, the result is issued as an asynchronous message.
If the recipient is an asynchronous TAC, the relevant program unit must read every single line of the result with an FGET call. The first FGET call supplies the header. Every subsequent call supplies one line of screen output.
The layout of the output is not subject to the compatibility guarantee, i.e. it may vary when changing to a new version of openUTM. Program units which evaluate the output from administration commands may therefore have to be adapted when a new version is installed.
Assignment of jobs to results for the recipient
When entering the operands of an asynchronous command, you can also enter a comment in inverted commas (“comment”). This comment can then be evaluated by the recipient for the results message.
As a comment you can, for example, enter a job number. The recipient can use this job number to identify the job.
In this case, the comment should be entered before the operand to ensure that job identification is always at the start of each message and is easy to address.
asynchronous command "comment" operands