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 and from the list of messages retained by MVS™. When a program no longer requires that a message be displayed or retained, it issues the DOM macro to delete the message.

When a program issues a WTO or WTOR macro, the system assigns an identification number to the message and returns this number in register 1 to the issuing program. When the display of this message is no longer needed, the issuing program can issue the DOM macro using the identification number that was returned in register 1.

MVS automatically invokes DOM for a WTOR when it receives the WTOR reply. You need only invoke DOM for a WTOR if the WTOR becomes obsolete before the system receives the reply. When the system receives the reply, the message is no longer highlighted on the MCS console screen. The message is eventually removed from the screen of an MCS console.

Environment

The requirements for the caller are different for LINKAGE=SVC and LINKAGE=BRANCH.

If you specify LINKAGE=SVC, the requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state or 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

If you specify LINKAGE=BRANCH, the requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state with PSW key 0-7
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt Status:	Enabled or disabled for I/O and external interrupts
Locks:	The caller may hold locks, but is not required to hold any
Control parameters:	Must be in the primary address space.

Programming requirements

None.

Restrictions

The following restrictions and limitations apply:

If the caller is executing in a sysplex, do not use SCOPE=SYSTEM, but rather SCOPE=SYSTEMS. DOM ignores SCOPE=SYSTEM if the caller is executing in a sysplex.
For any DOM parameters that allow a register specification, the value must be right-justified in the register, and the remaining bytes within the register must be zero.
Any authorized DOM parameters that are specified by an unauthorized program will cause a 157 abend. The only authorized parameter is SCOPE.

Register information

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code if you specified LINKAGE=BRANCH; otherwise, used as a work register by the system.

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=`field`	`field`: Four-byte value
MSGLIST=`list addr`	`list addr`: Symbol, RX-type address, or register (1) - (12).
TOKEN=`addr`	`addr`: Register (1) - (12), or an RX-type address.

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

,SCOPE=SYSTEM	Default: SCOPE=SYSTEMS
,SCOPE=SYSTEMS

,LINKAGE=SVC	Default: LINKAGE=SVC
,LINKAGE=BRANCH

Parameters

The parameters are explained as follows:

MSG=field

MSGLIST=list addr

TOKEN=addr

MSG=field specifies in register 1 the ID of a single message to be deleted. Register 1 contains the 32-bit identification number (the DOM id) of a WTO message to be deleted. Use this as input on the MSG parameter.

MSGLIST=list addr specifies the address of a list of one or more fullwords, each word containing the 32-bit identification number of a message to be deleted. You can end the list in one of two ways:

Use the COUNT parameter to specify how many entries are in the list.
Turn on the high-order bit in the last entry of the list.

Attention: Do not alter a DOM id 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. When you issue WTO or WTOR to write a message, you can choose a token value, and specify it as an input parameter to WTO or WTOR through the TOKEN parameter. To issue a DOM using a TOKEN, ignore the message ID returned by WTO or WTOR in register 1, and specify the token value instead, using the TOKEN parameter when you issue DOM. TOKEN is an alternate method for identifying messages, which is independent of the register 1 message ID. Specifying TOKEN with DOM will delete all messages specified with WTO and that particular TOKEN.

With TOKEN, authorized users may delete any messages originally issued under the same ASID and system ID. Unauthorized users may delete only those messages that 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. TOKEN is mutually exclusive with MSG, MSGLIST, and COUNT.

,COUNT=count addr

Specifies a field or register containing the 1-byte count of 4-byte message IDs associated with this request. The count must be from 1 to 60. If you specify COUNT, do not set the high-order bit on in the last entry of the DOM parameter list. If you specify COUNT in a register, ensure that it is right-justified and padded with zeros. If you do not specify COUNT, the message IDs are treated as 32-bit IDs. If an address is used, the address points to a 1-byte field that contains the count. COUNT is not valid with TOKEN.

,SCOPE=SYSTEM

,SCOPE=SYSTEMS

Specifies how to process the DOM request. If you specify SCOPE=SYSTEMS, the DOM request is to be communicated to other processors. If you specify SCOPE=SYSTEM, the DOM request is not to be communicated to other processors. If you do not specify SCOPE, the DOM request defaults to SCOPE=SYSTEMS.

You must specify SCOPE=SYSTEMS if you are running in a sysplex.

,LINKAGE=SVC

,LINKAGE=BRANCH

Specifies how DOM will receive control. LINKAGE=SVC specifies that linkage is by supervisor call, and LINKAGE=BRANCH specifies that linkage is by branch and link. LINKAGE=SVC is the default.

Use LINKAGE=BRANCH when you cannot issue an SVC.

Return and reason codes

Table 1. Return Codes for the DOM LINKAGE=BRANCH Macro
Hexadecimal Return Code	Meaning
00	Meaning: For LINKAGE=BRANCH, processing completed successfully. The system has accepted the request and will perform the deletion later.
40	Meaning: You issued DOM with LINKAGE=BRANCH, but the system could not obtain necessary storage. No processing was done.
4C	Meaning: You issued DOM with LINKAGE=BRANCH, but the system was unable to obtain storage for processing. No processing was done. This return code can occur as a result of unexpected error conditions in system storage.

There are no return codes from DOM LINKAGE=SVC.

Example 1

Issue a DOM by ID. The ID is in register 2.

R2     EQU     2

         DOM MSG=(R2)

Example 2

Issue a DOM by token.

         DOM TOKEN=READER
READER   DC    F'00000320'

Example 3

Issue a DOM by a list of IDs. The count is specified in a register. Use the branch-entry form of the macro.

R7     EQU     7

         L     R7,CURCOUNT               NUMBER OF ENTRIES IN LIST
         DOM MSGLIST=MYLIST,COUNT=(R7),SCOPE=SYSTEMS,LINKAGE=BRANCH
CURCOUNT DS    F
MYLIST   DS    60F