![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
Use the following command to enable the display of UIDs:
ncl> set event dispatcher sink netmgr displayuids true
Use the enable command to start an event sink that is ready to accept event messages from its outbound stream(s).
ncl> enable event dispatcher sink netmgr1_sink_a
If you receive an invalid name exception while attempting to enable an event sink, it indicates a problem with the defined object name characteristic. Compare the value of this parameter (using a show command in NCL) with the actual object's name in the DECdns namespace.
Use Option 10 of decnet_register to examine the namespace (for more information, refer to the DECnet-Plus DECdns Management guide).
The event sink generates events when it is enabled. By default, all events generated by some event dispatcher subentities, such as event sinks and outbound streams, are blocked by the sink's global filters (as is the case with outbound stream global filters). On the other hand, the specific filter for subentities such as the sink or outbound stream pass events from only that instance of the sink or outbound stream. That is, netmgr1_sink_a passes events from netmgr1_sink_a, but from no other sink. If you have set up your sink's filters to pass all event dispatcher sink events you might see various events posted when you enable the sink.
A sink always posts events directly to its sink client even if you do not have an outbound stream defined. If you have both sides of an event stream on the same node, you might see sink events posted twice: Once when the sink posts them to the client and again when the outbound stream delivers the event to the sink.
The sink probably will not generate many events. You can, however, eliminate redundant events by blocking the sink events at the outbound stream. For example:
ncl> block event dispatcher outbound stream netmgr1_obs - _ncl> global filter=((node, event dispatcher, sink), all)
You should block sink events at the outbound stream because:
The following example creates a user-specified outbound stream named netmgr1_obs.
ncl> create event dispatcher outbound stream netmgr1_obs - _ncl> maximum buffer size size (1)
If you create an outbound stream and accept all the default settings, the filter's specific setting is set to pass events generated by that outbound stream. The global setting is set to block for all events generated by event dispatcher entities. The filter's catch-all setting is set to pass. For more information about using event filters, see Section 12.2.
To identify events to filter for specific entity instances, define entries at the specific level. Define entries at the global level to filter for certain events, or all events, for an entity class. See the following example:
ncl> block event dispatcher outbound stream -
_ncl> netmgr1_obs specific filter = -
_ncl> ((node usa:.admin.art routing circuit ether-1), circuit change)
ncl> pass event dispatcher outbound stream -
_ncl> netmgr1_obs global filter = -
_ncl> ((routing, circuit), all) (1)
ncl> block event dispatcher outbound stream -
_ncl> netmgr1_obs specific filter = -
_ncl> ((node usa:.admin.art mop circuit una-0), all)
ncl> ignore event dispatcher outbound stream -
_ncl> netmgr1_obs specific filter = -
_ncl> ((node usa:.admin.art mop circuit una-0), load request completed)
ncl> pass event dispatcher outbound stream -
_ncl> netmgr1_obs global filter = -
_ncl> ((mop, circuit), all) (2)
ncl> pass event dispatcher outbound stream -
_ncl> netmgr1_obs global filter = -
_ncl> ((session control, application), all) (3)
ncl> set event dispatcher outbound stream -
_ncl> netmgr1_obs catch all filter = block (4)
The following is another example of filtering. It defines an additional outbound stream on the system and reports events from OSI transport entities.
ncl> pass event dispatcher outbound stream - _ncl> netmgr1_obs2 specific filter = - _ncl> ((node usa:.admin.artist osi transport local nsap aaaa), all) (1) ncl> pass event dispatcher outbound stream - _ncl> netmgr1_obs2 specific filter = - _ncl> ((node usa:.admin.artist osi transport local nsap remote nsap dddd), - _ncl> all) (2) ncl> ignore event dispatcher outbound stream - _ncl> netmgr1_obs2 specific filter = - _ncl> ((node usa:.admin.artist osi transport local nsap remote nsap dddd), - _ncl> reject sent) (3) ncl> block event dispatcher outbound stream - _ncl> netmgr1_obs2 global filter = - _ncl> ((osi transport, local nsap), all) (4) ncl> block event dispatcher outbound stream - _ncl> netmgr1_obs2 global filter = - _ncl> ((osi transport, local nsap, remote nsap), all) (5) ncl> set event dispatcher outbound stream netmgr1_obs2 - _ncl> catch all filter = block (6)
Once you have set up the event filter for an outbound stream, use the testevent command to check that the filter works according to your plan. The testevent command returns a message specifying the action of the filter used. For example:
ncl> testevent event dispatcher outbound stream netmgr1_obs - _ncl> event = ((node usa:.admin.artist routing circuit ether-1), - _ncl> adjacency state change)
Action = Pass Filter = Specific filter
If successful, this command returns an informational message showing which filter will be used and what action will be taken if the given event is posted.
Note
You cannot use a wildcard character with the testevent command's event argument.
The testevent command only analyzes the filter definitions for the outbound stream entity. It does not attempt to establish a connection to the event sink that will actually accept events from the specified outbound stream. Therefore, you can use the testevent command any time after you define a filter, even if the event sink does not yet exist.
The testevent command might reveal an error in your logic about event filtering for this outbound stream. If this occurs, see Section 12.3.15.1.
You cannot directly modify an event filter definition entry. If the testevent command described in the preceding section reveals that your filtering scheme is behaving differently from your intentions, you have four options:
Option 1
You cannot use this option to fix filter definition logic errors made in the specific filter. Corrections for the first option cover the simple cases and apply only to overriding logic errors made in the global filter and, to a lesser extent, in the catch-all filter's single value, pass or block. The following example shows one such definition:
ncl> block event dispatcher outbound stream netmgr1_obs -
_ncl> global filter = ((routing, circuit), circuit change)
ncl> set event dispatcher outbound stream netmgr1_obs catch all filter pass
If your actual intent was to block all routing circuit ether-2 circuit change events and let all other routing circuit events pass, you could enter the following subsequent commands:
ncl> block event dispatcher outbound stream netmgr1_obs -
_ncl> specific filter = (node usa:.admin.artist routing circuit ether-2, -
_ncl> circuit change)
ncl> pass event dispatcher outbound stream netmgr1_obs -
_ncl> global filter = ((routing, circuit), all)
Option 2
See Section 12.3.5 for information about defining filters on event sinks.
Option 3
For cases where the defined filter performs an undesired action, especially at the specific filter, your best option is to record the current, valid outbound-stream event filter definitions, record the other outbound stream parameter values, delete the outbound stream, and redefine it.
Use the NCL command-logging function and the show command to record the outbound stream entity definitions you want to use again in the redefined entity. For example:
ncl> set ncl logfile netmgr1_obs.ncl ncl> enable ncl logging ncl> show event dispatcher outbound stream netmgr1_obs all characteristics . . . [output] . . . ncl> disable ncl logging ! Close the output file.
Confirm that the outbound-stream state status attribute is set to OFF:
ncl> show event dispatcher outbound stream netmgr1_obs state node 0 event dispatcher outbound stream netmgr1_obs state = off ncl>
If the state is set to ON, select an appropriate time when the outbound stream can be temporarily turned off and use the shutdown command, which is described in more detail in Section 12.5.3.
If the state is set to on connected, on connecting, or on shutdown requested, select an appropriate time when the outbound stream can be temporarily turned off and use the disable command described in Section 12.6.1.
When the outbound stream entity's state is OFF, delete the outbound stream. For example:
ncl> delete event dispatcher outbound stream netmgr1_obs
Finally, use a text editor to modify the former outbound-stream characteristics that were recorded in the output NCL command file. Correct the event filter definitions and run the updated command file. For example:
ncl> netmgr1_obs.ncl
Option 4
To delete the old filter values and reinitialize them to their original default values when the outbound stream was created, use the following command:
ncl> reset event dispatcher outbound stream netmgr1_obs
New filter values take effect for the next event message sent by the event dispatcher to the outbound stream.
The following example enables a user-specified outbound stream named netmgr1_obs:
ncl> enable event dispatcher outbound stream netmgr1_obs
You can modify all outbound stream characteristics at any time by using the set command. Other changes, such as changing the sink node, require you to disable and then re-enable the outbound stream before the change takes effect. The following example uses set commands to change several parameters for outbound stream netmgr1_obs. You can enter consecutive set commands or include any combination of modifiable characteristics, separating each item with a comma.
ncl> set event dispatcher outbound stream netmgr1_obs - _ncl> connect retry timer 240, - (1) _ncl> connect timer enabled true, - (2) _ncl> disconnect timer 3600 (3) ncl> set event dispatcher outbound stream netmgr1_obs - _ncl> catch all filter pass (4) ncl> set event dispatcher outbound stream netmgr1_obs - _ncl> template port_1_osi_tp_template (5)
In the previous example, the set command performed the following on the existing definition of the netmgr1_obs outbound stream:
The set command also can modify the sink address, sink end user, sink node, and sink object characteristics.
When the outbound stream is created and its characteristics set to your satisfaction, and the corresponding event sink is created, defined, and enabled, you can enable the event stream, as the following example shows:
ncl> enable event dispatcher outbound stream netmgr1_obs
The outbound stream immediately tries to connect to the sink when you enable the outbound stream. If you cannot establish the connection to the sink, the outbound stream tries again after the connect retry timer expires. By default, the connect retry timer is enabled, and its value is 120 seconds. You can attempt an immediate connection with the connect command.
The sink can now receive event messages from the outbound stream and report them to the sink client.
The following example shows a typical event report. Note that event reports can differ because of the information they contain.
Event: PhaseIV Translation Failure (1) from: Node ADMIN:.Finance Routing, (2) at: 1995-02-26-09:17:11.950-05:00Iinf (3) PDU Header=%X812201361C004500000A490013AA000400774D410A490004 AA000400451320C301C0 (4) eventUid AE559D4F-39F4-CA11-80E8-AA000400904C (5) entityUid 359ABCC9-ACF2-CA11-8005-AA000400904C streamUid D57DB0E8-ACF2-CA11-8005-AA000400904C
You have the option of manually controlling the connection between an outbound stream and its event sink. Three NCL commands allow you to manage connections:
After the outbound stream is enabled, the event dispatcher automatically attempts to establish a connection to the sink when the connect timer enabled characteristic is set to its default value of true. Set this value to false if you want to manually create the connection between an outbound stream and its sink partner. When the connect timer enabled characteristic is set to false, the connect retry timer is not used, as the following example shows:
ncl> set node node-id event dispatcher outbound stream netmgr1_obs - _ncl> connect timer enabled false ncl> connect node node-id event dispatcher outbound stream netmgr1_obs
Note
Remember that the node-id you specify represents the node that is running the outbound stream. The node running the outbound stream might not have any association with the node running the event sink or the node upon which you are executing the connect command.
When the event dispatcher executes the connect command, it looks up the values of the following outbound stream characteristics in the order shown below and uses the first value that is not null.
If the sink object, sink node, and sink address are all null, the event dispatcher assumes the sink is on the local system and uses the sink end user characteristic when attempting a local connection.
If you want idle connections disconnected automatically, assign a non-zero value to the disconnect timer attribute for the outbound stream. You can terminate the connection at any time by using the disconnect command. Note that the disconnect command deletes the connection immediately. This might cause events in transit to be lost. Issue this command only if you have problems with the sink node and want to specify an event sink on a different, functioning node.
For example, assume that the event sink for outbound stream netmgr1_obs is located on .admin.netmgr1. With little advance notice, you learn that the sink node will be unavailable starting in approximately 5 minutes. You can use an already existing event sink that resides on a different system.
On an OpenVMS system, this event sink can be located by DECdns using the .admin.event_sinks.alternate_sink object name, as the following example shows:
ncl> disconnect event dispatcher - _ncl> outbound stream netmgr1_obs ncl> set event dispatcher outbound stream netmgr1_obs - _ncl> sink object .admin.event_sinks.alternate_sink ncl> connect event dispatcher outbound stream netmgr1_obs
You can also locate this event sink by using the .admin.netman2 sink node name, as the following example shows:
ncl> disconnect event dispatcher outbound stream netmgr1_obs ncl> set event dispatcher outbound stream netmgr1_obs - _ncl> sink node .admin.netman2 ncl> connect event dispatcher outbound stream netmgr1_obs
To perform an orderly shutdown of a connection between an outbound stream and its sink partner, use the shutdown command:
ncl> shutdown event dispatcher outbound stream netmgr1_obs
An orderly shutdown ensures the following:
There might be a delay before the shutdown completes. The outbound stream enters the "On Shutdown Requested" state and finishes transmitting all events on its queue to the event sink before shutting down.
An outbound stream remains enabled when there is no connection to an event sink. The absence of a connection might be caused by the following:
Because the outbound stream is enabled, it will read event messages from the event dispatcher queue, filter events, and perform all its functions when a connection is not established. Event messages queued to the outbound stream might exceed the buffers used by the outbound stream and might result in events being lost.
A special event called an events lost event is inserted into the event stream to indicate that one or more events could not be posted due to buffer overload at the outbound stream. The event dispatcher and event sink also use events lost. Examine event message to determine the source.
Use the shutdown command as part of the system's orderly shutdown process.
The following sections describe how to disable and delete event dispatcher entities.
To disable the event dispatcher entity, first disable all the children/subentities, that is, outbound stream, phase IV relay and sink subentities. If any one of these subentities is enabled, the disable event dispatcher directive fails. An error message might state that the outbound stream entities are still enabled. Other subentities might be enabled besides the outbound stream entity.
Using the disconnect (see Section 12.5.2) or shutdown (see Section 12.5.3) command with an outbound stream deletes only the connection between an outbound stream and its sink partner. The outbound stream is still enabled. To disable the outbound stream, use the disable command, as the following example shows:
ncl> disable event dispatcher outbound stream netmgr1_obs
PROFILE_VMS_019.HTML OSSG Documentation 2-DEC-1996 12:35:17.29
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.