HP OpenVMS Systems Documentation

1. Passes all events generated by the osi transport local nsap aaaa onto the event stream.
2. Passes all events generated by the osi transport local nsap remote nsap dddd, except for the reject sent event, because in the next step it is sent to the global filter.
3. Ignores the event, osi transport local nsap remote nsap dddd reject sent, causing the event dispatcher to next check the global filter setting.
4. Blocks all osi transport local nsap events. The osi transport local nsap aaaa events have already been passed in step one.
5. Blocks all osi transport local nsap remote nsap events. The osi transport local nsap remote nsap dddd events, except reject sent, have already been passed in step two.
6. All other events reported by all other entities on this system cannot pass onto the event stream managed by outbound stream netmgr1_obs2.

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.

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.

12.3.15.1 Correcting Outbound Stream Event Filters

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:

1. In limited cases, you can add a new filter definition that overrides an unwanted action at a lower level in the filtering scheme. For example, add a specific filter entry that performs the desired action, and the unwanted definition at the global filter will never be used for the event. However, this option may result in a cluttered outbound stream filter definition.
2. Define additional filtering on this outbound stream's event sink. This option also may be undesirable because the event sink filters apply to the event reports from all the outbound streams associated with the sink.
3. Record the current valid outbound stream event filter definitions and other outbound stream parameter values, delete the outbound stream, and redefine it.
4. Use the reset directive to reset all three types of filters to their default values and then set the correct filter actions.

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.

12.3.16 Enabling an Outbound Stream Entity

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:

1. Doubled the connect retry timer value from its default value of 120 seconds to 240 seconds.
2. Changed the connect timer enabled from false to true. The default value is true.
3. Increased the disconnect timer value from the default of 0 (which signifies that the connection between this outbound stream and its sink partner are never disconnected automatically) to 3600 seconds. This means that the connection is disconnected whenever it has been idle for one hour.
   The disconnect timer disconnects the link between nodes when there are no events to transmit, thus reducing network overhead. When the outbound stream has another event to send, it re-establishes the connection to the sink.
4. Changed the catch-all filter value from block to pass.
5. Identifies an OSI transport template used by this outbound stream's connections.

The set command also can modify the sink address, sink end user, sink node, and sink object characteristics.

12.3.18 Enabling an Outbound Event Stream

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.

12.4 Sample Event Report

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

1. Specifies the event.
2. Specifies the entity instance.
3. Specifies when the event occurred.
4. Specifies the argument for the event.
5. Specifies unique identification (UID) values for the various components involved.

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:

• connect
• disconnect
• shutdown

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

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.

• The value of the sink object characteristic is used as the full DECdns namespace object name for the sink.
• The values for the sink node and sink end user characteristics are used as the sink address.
• The value of the sink address characteristic is used as the sink address.

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.

12.5.2 Terminating a 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:

• All events posted prior to the shutdown are sent.
• No events are lost in transit because of the shutdown.
• The sink receives all events throughout the shutdown of an associated outbound stream.

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:

• Issuance of a disconnect or shutdown command
• Communication failures
• Absence of an event sink
• Connection not yet established

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.

12.6 Shutting Down Event Dispatching

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.

12.6.1 Disabling an Outbound Stream and Its Connection

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

When you enter the disable command, an existing connection between the outbound stream and its event sink is deleted. Simultaneously, the inbound stream is also deleted. By default, the system performs an orderly shutdown. Whenever possible, DIGITAL recommends that you perform orderly shutdowns of event stream connections.

If necessary you can abort the connection immediately with the following command:

ncl> disable event dispatcher outbound stream -
_ncl> netmgr1_obs method abort

When the disable command completes, the outbound stream's state status attribute is set to OFF. Once this condition exists, you can activate the outbound stream again by issuing enable command, or you can delete the outbound stream.

To delete an outbound stream, its state status has to be set to OFF. Then you can issue the following command:

ncl> delete event dispatcher outbound stream netmgr1_obs

Before deleting an event sink, use the disable command to set the sink's state status attribute to OFF:

ncl> disable event dispatcher sink netmgr1_sink_a

Disabling a sink terminates any existing connections with outbound streams. It also deletes all the inbound stream subentities corresponding to this sink. After disabling a sink, you can activate the event sink again by issuing the enable command. Or you can delete the event sink.

To delete an event sink, its state status has to be set to OFF. Then you can issue the following command:

ncl> delete event dispatcher sink netmgr1_sink_a