Asynchronous service MSGTAC

The asynchronous program unit MSGTAC is called:

• if openUTM outputs a Knnn or Pnnn message

• if MSGTAC is entered as the destination for this message.

How you enter MSGTAC as the message destination and how the messages that are passed are structured is described in the openUTM manual ”Messages, Debugging and Diagnostics”.

The MSGTAC service is given administration authorization and all keys of the application by openUTM , i.e. with the maximum authorization allowed.

If the MSGTAC program unit aborts with KCRCCC >= 70Z, openUTM locks it for the remainder of the application run (STATUS=OFF). It then needs to be released explicitly by the administrator (STATUS=ON). This rule does not apply if a program is aborted by a programmed PEND ER/FR.

openUTM writes messages for the message destination MSGTAC to the page pool. As long as warning level 2 for this page pool is not exceeded, you can be sure that none of these UTM messages will be lost.
Exception: The messages indicating that the warning level has been exceeded or not reached cannot always be sent to the MSGTAC program unit.

Programming notes

• The asynchronous program MSGTAC reads the message to the message area for the program unit with an FGET call. In this context, FGET calls should be repeated as often as necessary until the return code 10Z is set, to ensure that all pending UTM messages are read in a single program unit run.

• For each UTM message, there is a data structure available which can be used in the program unit to interpret the message contents. For C/C++, these structures are contained in the header file kcmsg.h; for COBOL they are contained in the COPY member KCMSGC.

• The MSGTAC program unit runs as an asynchronous service under the internal UTM user ID KDCMSGUS with KSET=MASTER and PERMIT=ADMIN.

• The MSGTAC service can only consist of one program unit run.

• In a program unit run, at least one message must be read with FGET as otherwise the program unit will be terminated abnormally.

• The service is started internally with the administrator TAC KDCMSGTC.

  openUTM supplies the KB header as follows:

  Fields in the KB header		Entries for MSGTAC
  COBOL	C/C++
  KCBENID	kcuserid	KDCMSGUS
  KCTACVG	kccv_tac	KDCMSGTC
  KCTACAL	kcpr_tac	KDCMSGTC
  KCLOGTER	kclogter	KDCMSGLT
  KCTERMN	kctermn	MT

• The MSGTAC program unit can use the administration program interface and it can issue administration commands. In particular, the MSGTAC program unit can issue the KDCS calls DADM and PADM to administer DPUT messages and printers; see the openUTM manual “Administering Applications”.

Generation notes

• There can be only one MSGTAC program unit per application.

• The MSGTAC program unit must be defined in the TAC statement with

  TAC KDCMSGTC,PROGRAM=... .

Example of a MSGTAC program unit

The MSGTAC program unit NOHACK is designed to prevent unauthorized users from gaining access to a UTM application. If more than three invalid attempts are made to sign on via an LTERM partner (with an invalid user ID, an incorrect password or the wrong ID card), the connection to the terminal is to be aborted. This will require additional preparatory measures (see also the openUTM manual ”Messages, Debugging and Diagnostics”).

• Preparations:

  1. Call the UTM tool KDCMMOD.

  2. Issue the GEN command, specifying the name of the message module.

  3. Use MODMSG commands to define MSGTAC as an additional destination for the messages K008, K033 and K094.

  4. Compile the source program written so far and link it to the application.

  5. Define the KDCDEF statement MESSAGE in the message module.

  6. Define KDCPTRMA in the TAC statement.

  A more elegant solution would be to write the specifications for points 2 and 3 to a file and then to use this as an input file for point 1.

• Implementing the MSGTAC program unit:

  The MSGTAC program unit NOHACK counts the number of incorrect attempts in a TLS. If openUTM accepts a sign-on attempt to the application (message K008 or K033), this TLS is deleted again.
  If three consecutive incorrect attempts are followed by a fourth incorrect attempt, the corresponding terminal is to be released by means of "asynchronous administration". This happens with an FPUT call with KCRN = "KDCPTRMA" and a message area with the contents PTERM=pterm, ACT=DIS (see also the openUTM manual “Administering Applications”).
  The administration command is then written with LPUT to the user log file and the TLS is deleted. Examples in C are given in section "Example: MSGTAC event service" and in and COBOL in section "Example of an asynchronous MSGTAC program unit" respectively.

  Each K message is read with FGET by the MSGTAC program unit. After one K message has been “processed”, FGET immediately reads the next K message within the same program unit run. A list of all the K messages is provided in the openUTM manual ”Messages, Debugging and Diagnostics”.