Initiate or cancel message subscription
Component: | BS2000 |
Functional area: | Operator terminal control |
Domain: | CONSOLE-MANAGEMENT |
Privileges: | OPERATING |
Routing code: | E |
Function
Logical BS2000 operator terminals (consoles) in particular may be required to respond to certain system messages. The MODIFY-MSG-SUBSCRIPTION command instructs the UCON message distribution mechanism to deliver certain system messages to a specific operator terminal (message subscription) or to cancel an existing subscription. A message subscription is not a request for messages to be output exclusively on a given operator terminal.
The command applies only to the operator terminal on which it is issued. It has no effect on other operator terminals.
The SHOW-MSG-SUBSCRIPTION command provides details of the current message subscription arrangements.
Format
MODIFY-MSG-SUBSCRIPTION | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
ADD-MSG-ID = *NONE / list-poss(32): <name 1..7>
Specifies whether a message subscription is required for the operator terminal.
Note
A message subscription can be suppressed in full or in part with the SET-MSG-SUPPRESSION command.
ADD-MSG-ID = list-poss(32): <name 1..7>
Specifies the name (ID) of the message which is to be delivered to the operator terminal under the message subscription mechanism. One message subscription is added for each name specified. A 7-character name matches exactly one message ID; a shorter name (1 to 6 characters) matches a group of message IDs all beginning with the specified string. It is not possible to subscribe to messages which required a response.
REMOVE-MSG-ID = *NONE / *ALL / list-poss(32): <name 1..7>
Specifies whether message subscriptions are to be canceled for the operator terminal.
REMOVE-MSG-ID = *ALL
All message subscriptions ordered for the operator terminal are canceled.
REMOVE-MSG-ID = list-poss(32): <name 1..7>
Specifies the names (message IDs) of the message subscriptions which are to be canceled. One message subscription is canceled for each name specified, provided the subscription actually exists.
To cancel a message subscription you must specify the same name as was used when the subscription was ordered. For example, a subscription to all messages beginning with the string ABC123 (corresponding to ADD-MSG-ID=ABC123) cannot be canceled with REMOVE-MSG-ID=ABC1.
Similarly, it is not possible to reduce the number of messages in a subscription by canceling a specific message, e.g. using REMOVE-MSG-ID=ABC1234. The SET-MSG-
SUPPRESSION command is provided for this purpose.
ADD-SENDER = *NONE / *USER-ID(...) / *TSN(...) / *CONSOLE(...)
Messages from the users specified are to be routed to the console.
The operand is only allowed when input at a physical or logical operator terminal. Input form an interactive task with the OPERATING privilege is not allowed.
ADD-SENDER = *NONE
Default value.
No messages are added on the basis of sender attributes.
ADD-SENDER = *USER-ID(...)
Messages that are sent by user tasks or system tasks with the specified user ID (via MSG7[X] or TYPIO macro calls) are delivered.
USER-ID = *NONE / list-poss(32): <name 1..8>
One or several user IDs can be specified.
The default value is *NONE, i.e. messages are not delivered.
ADD-SENDER = *TSN(...)
Messages that are sent by user tasks or system tasks with the specified TSNs (via MSG7[X] or TYPIO macro calls) are delivered.
TSN = *NONE
Default value. Messages are not delivered.
TSN = *SYSTEM-TASKS
All console messages generated by system tasks are delivered.
TSN = list-poss(32): <alphanum-name 1..4>
Messages that are sent by user tasks or system tasks with the specified TSNs are delivered.
Leading zeroes do not have to be entered for the TSNs; TSN=AB is interpreted as ''BLANK''BLANK'AB' and not as '00AB'.
ADD-SENDER = *CONSOLE(...)
Messages sent by the specified physical or logical consoles are delivered.
CONSOLE = *NONE / list-poss(32): <name 2..2> / <name 4..4>
One or more consoles can be specified.
Physical consoles are specified through a two-position mnemonic name and logical consoles by means of a four-position authorization name.
The default value is *NONE, i.e. messages are not delivered.
REMOVE-SENDER = *NONE / *ALL / *USER-ID(...) / *TSN(...) / *CONSOLE(...)
Message subscriptions previously defined through the sender attributes with MODIFY-MSG-SUBSCRIPTION (ADD-SENDER operand) are removed.
The operand is only allowed when entered from a physical or logical console. Input from an interactive task with the OPERATING privilege is not allowed.
REMOVE-SENDER = *NONE
Default value. No message subscriptions are removed.
REMOVE-SENDER = *ALL
All message subscriptions that were previously defined via sender attributes (ADD-SENDER operand) are removed.
REMOVE-SENDER = *USER-ID(...)
Messages from specific user IDs that were previously defined via ADD-SENDER=*USER-ID(...) are removed.
USER-ID = *ALL / list-poss (32): <name 1..8>
One or several user IDs for which message subscription is to be removed can be specified.
The default value is *ALL, i.e. messages from all user IDs are removed.
REMOVE-SENDER = *TSN(...)
Messages from specific TSNs that were previously specified with ADD-SENDER=*TSN(...) are removed.
TSN = *ALL / *SYSTEM-TASKS / list-poss (32): <alphanum-name 1..4>
One or several TSNs for which message subscription is to be removed can be specified.
The default value is *ALL, i.e. messages from all TSNs are removed.
REMOVE-SENDER = *CONSOLE(...)
Messages from specific consoles that were previously specified with ADD-SENDER=*CONSOLE(...) are removed.
CONSOLE = *ALL / list-poss (32): <name 2..2> / <name 4..4>
One or several consoles for which message subscription is to be removed can be specified.
The default value is *ALL, i.e. messages from all consoles are removed.
DELIVER-OTHER-MSG = *UNCHANGED / *YES / *NO
Governs whether the delivery of other (nonsubscription) messages to the operator terminal is to be affected.
This operand is allowed only if the command is entered at a physical or logical operator terminal.
DELIVER-OTHER-MSG = *UNCHANGED
The delivery of other (nonsubscription) messages to the operator terminal is unchanged.
DELIVER-OTHER-MSG = *YES
Any previously imposed suppression of nonsubscription messages is canceled.
DELIVER-OTHER-MSG = *NO
Any nonsubscription messages are not delivered to the operator terminal, with the exception of messages requiring a response and messages directed explicitly to the operator terminal.
Notes
The command can be issued at all operator terminals, which means at physical and logical operator terminals ($CONSOLE applications) and in interactive tasks with the OPERATING privilege. At physical and logical operator terminals the command affects the delivery of messages to the operator terminal from which the command was issued. In interactive tasks with the OPERATING privilege the command has consequences for the viewing of a system event stream (see the command SHOW-SYSEVENT-LOG TYPE=*SYSTEM). For that reason the DELIVER-OTHER-MSG operand is not available in an interactive task, as suppressing the display of undirected messages (value *NO) would in effect be identical with relinquishing all the operator roles for that task (see the RELEASE-OPERATOR-ROLE command).
Suppression of the delivery of individual messages with the aid of the SET-MSG-SUPPRESSION command takes precedence over a message subscription initiated with the MODIFY-MSG-SUBSCRIPTION command. That means that it is possible to subscribe to a group of messages (e.g. all those with a message ID beginning with the string ABC) at an operator terminal and to exclude individual message IDs (e.g. message ABC1234) from the subscription set with the aid of the SET-MSG-SUPPRESSION command.
The messages subscriptions specified with the REMOVE-MSG-ID and REMOVE-SENDER operands are always the first to be removed when the command is executed. The message subscriptions specified with the ADD-MSG-ID and ADD-SENDER operands are added to the subscription set.
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | Command executed without error | |
2 | 0 | NBR0091 | Some message IDs ignored |
1 | CMD0202 | Syntax error | |
32 | NBR0034 | Error in command execution | |
64 | CMD0216 | Required authorization not available |