HP OpenVMS Systems Documentation

Before setting up the outbound stream, decide how you want to identify the associated local or remote event sink. The sink's identifying characteristics can be any of the following parameters to the set command:

• The full DECdns object name of the sink object associated with this outbound stream.
• The full DECdns node name of the sink associated with this outbound stream, and the end-user specification of the associated sink.
• The protocol tower of the sink associated with this outbound stream.

DECdns Object Name

If .ADMIN.EVENT_SINKS.SINK_A is the DECdns object name for the sink associated with the netmgr1_obs outbound stream, the following example shows the set command used to form the affiliation:

ncl> set event dispatcher outbound stream netmgr1_obs -
_ncl> sink object .admin.event_sinks.sink_a

You should identify network components by their DECdns object name. If the location of a sink object defined in the DECdns namespace changes, the namespace administrator can easily update information about the change by modifying the object's single entry in the DECdns namespace. For more information, see the DECnet-Plus DECdns Management guide. Also see Section 12.3.9 for related information about the set object name command used with the corresponding event sink.

DECdns Node Name

If you choose not to define a DECdns object entry for a sink, use the sink node name and end-user specification, or use the sink address. For example:

ncl> set event dispatcher outbound stream netmgr1_obs -
_ncl> sink node 0, sink end user number = 82

In the previous example, leaving sink node 0 (zero) indicates that the event sink resides on the local system. If the event sink resides on a system that is different from the outbound stream's system, specify the full DECdns node name.

The end-user specification for the sink consists of one of the following:

• number = number (default = 82)
• name = name
• uic = [uic-identifier]username
• fullname = full-name

The end-user specification corresponds to the object number or name, and defaults to the standard event sink supplied on the node.

You must specify a matching end-user specification on the event sink to associate the outbound stream and the event sink. For more information about matching end-user specifications for outbound streams and sinks, see Section 12.3.10.

Session Control Towers

If the event sink resides on a system that is different from the outbound stream's system, you can specify the remote sink by specifying the session control towers (sink address) of the remote node.

To find the towers of the destination sink node, enter the following NCL command on that node:

ncl> show node 0 address

If the event sink resides on the same (local) node as the outbound stream, set the sink node using either the node's full DECdns node name, or enter 0, which indicates the local node. For example:

ncl> set event dispatcher outbound stream netmgr1_obs sink node 0

If neither the sink node nor sink address attributes has been set, the events for this outbound stream will be logged to the local node sink by default.

12.3.4 Creating an Event Sink

The following example creates an event sink named netmgr1_sink_a:

ncl> create event dispatcher sink netmgr1_sink_a -
_ncl> maximum buffer size size (1)

1. Allows you to assign a maximum buffer size.
   For OpenVMS systems, the default maximum buffer size is 16384 bytes.
   The buffer size must be large enough to hold the event dispatcher sink entity's events lost event. NCL returns an insufficient resources exception if the value is too low.
   If you notice that you receive a high events lost count, this might indicate that the maximum buffer size is too small.
   If over time you notice that the maximum buffer size value seems inadequate, you must delete the event sink and redefine it with a higher value. See Section 12.6.2 for the steps involved in deleting an event sink.

In most cases, the event filters defined on outbound streams sufficiently manage event reports sent to an event sink. By default, the specific and global filters are defined to pass this sink's pseudo-events and the catch-all filter is set to pass. DIGITAL recommends that you define the filters at each source node where the outbound streams reside because, in cases where the source and sink reside on different nodes, setting up filters at the source avoids unnecessary network traffic between the source node and the sink node. Also, a consistent network management policy about where event filtering will occur can avoid confusion, especially when several network managers work throughout the network.

You have the option of defining event filters for an event sink. The filters apply to event messages received from all outbound streams that use this sink. That is, you cannot designate selected filter entries corresponding to incoming events from a specific outbound stream. The definition of event filters for event sinks is similar to the process used with outbound streams. See Section 12.2 and Section 12.3.14 for related information.

In the following example, assume that 10 outbound streams from 10 different systems let the station running event from all hdlc link logical station entities pass into the event stream sent to a sink called netmgr1_sink_b. If you decide this information is not important for the final report, you can filter it out. For example:

ncl> block event dispatcher sink -
_ncl> netmgr1_sink_b global filter = -
_ncl> ((hdlc, link, logical station), station running)

Once you have set up the event filter for an event sink, 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. See the following example:

ncl> testevent event dispatcher sink -
_ncl> netmgr1_sink_b event = -
_ncl> ((node usa:.admin.artist hdlc link link-id -
_ncl> logical station station-id), station running)

Action = Block
Filter = Global filter

The testevent command might reveal an error in your logic about event filtering for this event sink. If this occurs, see Section 12.3.7.

12.3.7 Modifying an Event Sink Filter

The specific and global filter trees can only be modified by the pass, block and ignore directives. You can enter a new definition for the event. The new definition supersedes any previous definitions.

To delete the previous filter values you set and reinitialize them to their default values when the event sink was created, use the following command:

ncl> reset event dispatcher sink netmgr1_sink_b

See Section 12.3.15.1 for related information.

After a sink receives and filters an event, the event message is queued to the sink client. The sink client delivers the event message as an event report to a specified destination.

The client type characteristic can be set only when the event dispatcher sink entity is disabled (that is, when the sink state is off). Attempts to set the characteristic when the sink state is on result in an error message.

DECnet-Plus provides three types of sink clients or destinations:

1. Console sink client
   Sends ASCII-formatted event reports to the system console, which is a system process that receives input from processes (like EVD) that want to inform a system operator or network manager of a particular status. Console sink client is the default.
   The sink client sends ASCII-formatted event reports to OPCOM. Sometimes, events are split into two OPCOM messages when only one OPCOM message is necessary for the event. All network operator terminals (terminals enabled through specification of the DCL command reply/enable=network) display these events.
   The following example specifies the console sink client. (See Figure 12-4 for the relationship of the sink subentity in the event dispatcher entity hierarchy.)

   ncl> set event dispatcher sink netmgr1_sink_a - _ncl> client type console

2. Device sink client
   Sends ASCII-formatted event reports to devices such as terminals or line printers. The following example specifies the device sink client:

   ncl> set event dispatcher sink netmgr1_sink_a - _ncl> client type device ncl> set event dispatcher sink netmgr1_sink_a - _ncl> device name "full-device-name"

3. Formatted file sink client
   Sends ASCII-formatted event reports to a file. To execute this command, you must be logged in as SYSTEM. The following example renames the default sink client file to a nondefault file name:

   ncl> set event dispatcher sink netmgr1_sink_a - _ncl> client type file ncl> set event dispatcher sink netmgr1_sink_a - _ncl> file name file-specification

   
   You should set the sink client type before the sink is enabled and inbound streams are created.

The DECdns namespace administrator can use option 10 of the decnet_register utility to register each event sink as an object in the namespace. For more information about the registration process, refer to the DECnet-Plus DECdns Management.

Once the event sink is defined as an object in the namespace, you can use the set command so that the DECnet-Plus Session Control layer on the sink node can deliver incoming event messages sent by outbound streams that used the DECdns object name for the sink. For example, if .admin.event_sinks.primary_sink is the object name in the namespace for an event dispatcher sink netmgr1_sink_a entity:

ncl> set event dispatcher sink netmgr1_sink_a -
_ncl> object name .admin.event_sinks.primary_sink

For the event sink, you must set an end-user specification, which can be one of the following:

• number = number
• name = name
• uic = [uic-identifier]username
• fullname = full-name

The default is number = 82.

Make sure that the end-user specification for both the sink and outbound stream match.

On an OpenVMS system, if you issue the following command on system .admin.finance, you need to issue an additional command to associate the sink and the outbound stream when setting up the outbound stream.

ncl> set event dispatcher sink netmgr1_sink end user name = accounting

The following example shows how to issue the additional command. Specify the system where the sink is located and the same end-user name as specified for the sink.

ncl> set event dispatcher outbound stream netmgr1_obs -
_ncl> sink node .admin.finance, sink end user name = accounting

You can disable the display of UIDs as part of an event message by setting the displayUIDs attribute to false. For example:

ncl> set event dispatcher sink netmgr displayuids false

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:

• Local sink events are reported directly by the sink.
• Only events from the local sink are blocked. Any events received from remote systems are reported.
• It reduces system and network overhead when you block events at the outbound stream.

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)

1. Allows you to assign a maximum buffer size.
   For OpenVMS systems, the default maximum buffer size is 16384 bytes.
   The buffer size must be large enough to hold the event dispatcher outbound stream entity's events lost event. NCL returns an insufficient resources exception if the value is too low.
   If you notice that you receive a high events lost count, this might indicate that the maximum buffer size is too small.
   If over time you notice that the maximum buffer size value seems inadequate, you must delete the outbound stream and redefine it with a higher value. See Section 12.6.1 for the steps involved in deleting an outbound stream.

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)

1. All events generated by all routing circuit entities, except for any circuit change events reported by the routing circuit ether-1 entity, are passed on to the event stream.
2. With one exception, all events reported by the mop circuit una-0 entity are not allowed to pass. The defined exception is that any load request completed events reported by the mop circuit una-0 entity can pass, because:
   • The mop circuit una-0 load request completed events were ignored on the specific setting, causing the event dispatcher to examine filter entries at the next level, the global setting.
   • The filter's global setting entry specifies that events reported by any mop circuit entities, including the single mop circuit una-0 load request completed event that was ignored in the preceding specific setting, plus any other mop circuit entities (for example, mop circuit una-1 events), can pass.
3. All events reported by all session control application entities can pass.
4. Every event reported by all other entities on this system cannot pass on to the event stream managed by outbound stream netmgr1_obs. Remember, however, that additional outbound streams can be defined on this system and one or more of those outbound streams might permit the forwarding of event messages disallowed by netmgr1_obs. The event dispatcher checks all outbound streams that are enabled on its system.

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)