DOM — Delete operator message

Description

The DOM macro deletes an operator message or group of messages from the display screen of the operator's console. It can also prevent messages from ever appearing on any operator's console. When a program no longer requires that a message be displayed, it can issue the DOM macro to delete the message.

Depending on the timing of the DOM relative to the WTO(R), the message may or may not be displayed. If the message is being displayed, it is removed when space is required for other messages.

When a WTO or WTOR macro is issued, the system assigns an identification number to the message and returns this number (24 bits right-justified) to the issuing program in general register 1. When you no longer need this message displayed, issue the DOM macro using the identification number that was returned in general register 1.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and any PSW key.
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31- or 64-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in the primary address space.

Programming requirements

None.

Restrictions

If you are deleting messages by lists of DOM IDs, you cannot delete more than 60 at a time.

Register information

Input register information

Before issuing the DOM macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Used as work registers by the system
2-14: Unchanged
15: Used as a work register by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

The DOM macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede DOM.

DOM

␢	One or more blanks must follow DOM.

MSG=`addr`	`addr`: Register (1) - (12), or an address.
MSGLIST=`list addr`	`list addr`: Symbol, RX-type address, or register (1) - (12).
TOKEN=`addr`	`addr`: Register (1) - (12), or an address.

,COUNT=`addr`	`addr`: Register (2) - (12), or an address.

Parameters

The parameters are explained as follows:

MSG=addr

MSGLIST=list addr

Specifies the message numbers of messages to be deleted.

For MSG, the address or register contains the 32-bit, right-justified identification number of the message to be deleted. Use this parameter to delete a single message.

For MSGLIST, the address is of a list of one or more fullwords, each word containing a 32-bit, right-justified identification number of a message to be deleted. A maximum of 60 identification numbers may be in the message list. If more than 60 identification numbers are in the list, only the first 60 are processed. Begin the list on a fullword boundary. When you are not using the COUNT parameter, indicate the end of the list by setting the high-order bit of the last fullword entry to 1.

Attention: DOM ids should not be altered from the 32-bit value returned in register 1 by the WTO or WTOR macro, except to turn on the high-order bit (x'80000000') in the last entry in a list.

,TOKEN=addr

Specifies a field or register containing a 4-byte token that is associated with messages to be deleted. Using the TOKEN parameter is an alternate method for identifying messages, which is independent of the register 1 message ID. When you issue WTO or WTOR to write a message, you can specify a token value. To delete that WTO or WTOR message, specify the same token value by issuing DOM with the TOKEN parameter. You cannot use the token value on the DOM macro unless you specified that token value on the WTO or WTOR macro that wrote the message. Issuing DOM with the TOKEN parameter deletes all messages issued through WTO or WTOR with the same token value. Unauthorized users may delete only those messages which were originally issued under the same jobstep TCB, ASID and system ID. The value of the token may not be the same as the ID that was returned in register 1 after a WTO or WTOR. This keyword is mutually exclusive with the MSG, MSGLIST, and COUNT keywords.

,COUNT=addr

The count field or register contains the one-byte count of messages to be deleted (specified on the MSG or MSGLIST parameters) associated with this request. The count value must be from 1 to 60. If this keyword is used, the issuer must not set the high order bit on in the last entry of the DOM parameter list. If this keyword is not specified, the DOM ids are treated as 32-bit ids. If an address is used instead of a register, the address points to a 1-byte field which contains the count. The COUNT keyword is invalid with the TOKEN keyword.

Note: For any DOM keywords that allow a register specification, the value must be right-justified in the register and the remaining bytes within the register must be zero.

Example 1

Delete an operator message whose message id is in register 1.

DOM MSG=(1)

Example 2

Delete a number of operator messages. The COUNT parameter indicates how many messages are to be deleted.

DOM MSGLIST=ID3,COUNT=COUNT4

Example 3

Delete all messages issued with a particular token.

DOM TOKEN=TOKEN1