Document revision date: 15 July 2002

If successful, the SYS$LAVC_DEFINE_NET_COMPONENT subroutine creates a COMP data structure and returns its ID value. This subroutine copies user-specified parameters into the data structure and sets the reference count to zero.

The component ID value is a 32-bit value that has a one-to-one association with a network component. Lists of these component IDs are passed to SYS$LAVC_DEFINE_NET_PATH to specify the components used when a packet travels from one node to another.

E.4.2 Error Messages

SYS$LAVC_DEFINE_NET_COMPONENT can return the error condition codes shown in the following table.

Condition Code	Description
SS$_ACCVIO	This status is returned for the following conditions: No access to the network component name buffer descriptor No access to the network component name buffer No access to the component's LAN hardware address if a nonzero value was specified No access to the component's LAN DECnet address if a nonzero value was specified No access to the lan_hardware_addr string descriptor No access to the lan_decnet_addr string descriptor No write access to the component_id_value address No access to the component_type address No access to the nodename_length address No access to the argument list
SS$_DEVACTIVE	Analysis program already running. You must stop the analysis by calling the SYS$LAVC_DISABLE_ANALYSIS before you define the network components and the network component lists.
SS$_INSFARG	Not enough arguments supplied.
SS$_INVCOMPTYPE	The component type is either 0 or greater than or equal to COMP$C_INVALID.
SS$_IVBUFLEN	This status value is returned under the following conditions: The component name has no characters (length = 0). Length of the component name is greater than COMP$C_MAX_NAME_LEN. The node name has no characters (length = 0) and the component type is COMP$C_NODE. The node name has more than 8 characters and the component type is COMP$C_NODE. The lan_hardware_addr string descriptor has fewer than 6 characters. The lan_decnet_addr has fewer than 6 characters.

E.5 Creating a Network Component List

The SYS$LAVC_DEFINE_NET_PATH subroutine creates a directed list of network components between two network nodes. A directed list is a list of all the components through which a packet passes as it travels from the failure analysis node to other nodes in the cluster network.

Use the following format to specify the parameters:

STATUS = SYS$LAVC_DEFINE_NET_PATH (
network_component_list,
used_for_analysis_status,
bad_component_id )

Table E-5 describes the SYS$LAVC_DEFINE_NET_PATH parameters.

Table E-5 SYS$LAVC_DEFINE_NET_PATH Parameters

Parameter	Description
network_component_list	Address of a string descriptor for a buffer containing the component ID values for each of the components in the path. List the component ID values in the order in which a network message travels through them. Specify components in the following order: Local node Local LAN adapter Intermediate network components Remote network LAN adapter Remote node You must list two nodes and two LAN adapters in the network path. The buffer length must be greater than 15 bytes and less than 509 bytes.
used_for_analysis_status	Address of a longword status value that is written. This status indicates whether this network path has any value for the network failure analysis.
bad_component_id	Address of a longword value that contains the erroneous component ID if an error is detected while processing the component list.

E.5.1 Status

This subroutine creates a directed list of network components that describe a specific network path. If SYS$LAVC_DEFINE_NET_PATH is successful, it creates a CLST data structure. If one node is the local node, then this data structure is associated with a PEDRIVER channel. In addition, the reference count for each network component in the list is incremented. If neither node is the local node, then the used_for_analysis_status address contains an error status.

The SYS$LAVC_DEFINE_NET_PATH subroutine returns a status value in register R0, as described in Table E-6, indicating whether the network component list has the correct construction.

Table E-6 SYS$LAVC_DEFINE_NET_PATH Status

Status	Result
Success	The used_for_analysis_status value indicates whether the network path is useful for network analysis performed on the local node.
Failure	If a failure status returned in R0 is SS$_INVCOMPID, the bad_component_id address contains the value of the bad_component_id found in the buffer.

E.5.2 Error Messages

SYS$LAVC_DEFINE_NET_PATH can return the error condition codes shown in the following table.

Condition Code	Description
SS$_ACCVIO	This status value can be returned under the following conditions: No access to the descriptor or the network component ID value buffer No access to the argument list No write access to the used_for_analysis_status address No write access to the bad_component_id address
SS$_DEVACTIVE	Analysis already running. You must stop the analysis by calling the SYS$LAVC_DISABLE_ANALYSIS function before defining the network components and the network component lists.
SS$_INSFARG	Not enough arguments supplied.
SS$_INVCOMPID	Invalid network component ID specified in the buffer. The bad_component_id address contains the failed component ID.
SS$_INVCOMPLIST	This status value can be returned under the following conditions: Fewer than two nodes were specified in the node list. More than two nodes were specified in the list. The first network component ID was not a COMP$C_NODE type. The last network component ID was not a COMP$C_NODE type. Fewer than two adapters were specified in the list. More than two adapters were specified in the list.
SS$_IVBUFLEN	Length of the network component ID buffer is less than 16, is not a multiple of 4, or is greater than 508.
SS$_RMTPATH	Network path is not associated with the local node. This status is returned only to indicate whether this path was needed for network failure analysis on the local node.

E.6 Starting Network Component Failure Analysis

The SYS$LAVC_ENABLE_ANALYSIS subroutine starts the network component failure analysis.

Example: The following is an example of using the SYS$LAVC_ENABLE_ANALYSIS subroutine:

STATUS = SYS$LAVC_ENABLE_ANALYSIS ( )

E.6.1 Status

This subroutine attempts to enable the network component failure analysis code. The attempt will succeed if at least one component list is defined.

SYS$LAVC_ENABLE_ANALYSIS returns a status in register R0.

E.6.2 Error Messages

SYS$LAVC_ENABLE_ANALYSIS can return the error condition codes shown in the following table.

Condition Code	Description
SS$_DEVOFFLINE	PEDRIVER is not properly initialized. ROOT or PORT block is not available.
SS$_NOCOMPLSTS	No network connection lists exist. Network analysis is not possible.
SS$_WASSET	Network component analysis is already running.

E.7 Stopping Network Component Failure Analysis

Example: The following is an example of using SYS$LAVC_DISABLE_ANALYSIS:

STATUS = SYS$LAVC_DISABLE_ANALYSIS ( )

This subroutine disables the network component failure analysis code and, if analysis was enabled, deletes all the network component definitions and network component list data structures from nonpaged pool.

E.7.1 Status

SYS$LAVC_DISABLE_ANALYSIS returns a status in register R0.

E.7.2 Error Messages

SYS$LAVC_DISABLE_ANALYSIS can return the error condition codes shown in the following table.

Condition Code	Description
SS$_DEVOFFLINE	PEDRIVER is not properly initialized. ROOT or PORT block is not available.
SS$_WASCLR	Network component analysis already stopped.

NISCA is the transport protocol responsible for carrying messages, such as disk I/Os and lock messages, across Ethernet and FDDI LANs to other nodes in the cluster. The acronym NISCA refers to the protocol that implements an Ethernet or FDDI network interconnect (NI) according to the System Communications Architecture (SCA).

Using the NISCA protocol, an OpenVMS software interface emulates the CI port interface---that is, the software interface is identical to that of the CI bus, except that data is transferred over a LAN. The NISCA protocol allows OpenVMS Cluster communication over the LAN without the need for any special hardware.

This appendix describes the NISCA transport protocol and provides troubleshooting strategies to help a network manager pinpoint network-related problems. Because troubleshooting hard component failures in the LAN is best accomplished using a LAN analyzer, this appendix also describes the features and setup of a LAN analysis tool.

The NISCA protocol is an implementation of the Port-to-Port Driver (PPD) protocol of the SCA.

F.1.1 SCA Protocols

As described in Chapter 2, the SCA is a software architecture that provides efficient communication services to low-level distributed applications (for example, device drivers, file services, network managers).

The SCA specifies a number of protocols for OpenVMS Cluster systems, including System Applications (SYSAP), System Communications Services (SCS), the Port-to-Port Driver (PPD), and the Physical Interconnect (PI) of the device driver and LAN adapter. Figure F-1 shows these protocols as interdependent levels that make up the SCA architecture. Figure F-1 shows the NISCA protocol as a particular implementation of the PPD layer of the SCA architecture.

Figure F-1 Protocols in the SCA Architecture

Table F-1 describes the levels of the SCA protocol shown in Figure F-1.

Table F-1 SCA Protocol Layers

Protocol	Description
SYSAP	Represents clusterwide system applications that execute on each node. These system applications share communication paths in order to send messages between nodes. Examples of system applications are disk class drivers (such as DUDRIVER), the MSCP server, and the connection manager.
SCS	Manages connections around the OpenVMS Cluster and multiplexes messages between system applications over a common transport called a virtual circuit (see Section F.1.2). The SCS layer also notifies individual system applications when a connection fails so that they can respond appropriately. For example, an SCS notification might trigger DUDRIVER to fail over a disk, trigger a cluster state transition, or notify the connection manager to start timing reconnect (RECNXINTERVAL) intervals.
PPD	Provides a message delivery service to other nodes in the OpenVMS Cluster system. PPD Level Description Port-to-Port Driver (PPD) Establishes virtual circuits and handles errors. Port-to-Port Communication (PPC) Provides port-to-port communication, datagrams, sequenced messages, and block transfers. "Segmentation" also occurs at the PPC level. Segmentation of large blocks of data is done differently on a LAN than on a CI or a DSSI bus. LAN data packets are fragmented according to the size allowed by the particular LAN communications path, as follows: Port-to-Port Communications Packet Size Allowed Ethernet-to-Ethernet 1498 bytes FDDI-to-Ethernet 1498 bytes FDDI-to-Ethernet-to-FDDI 1498 bytes FDDI-to-FDDI 4468 bytes Note: The default value is 1498 bytes for both Ethernet and FDDI. Transport (TR) Provides an error-free path, called a virtual circuit (see Section F.1.2), between nodes. The PPC level uses a virtual circuit for transporting sequenced messages and datagrams between two nodes in the cluster. Channel Control (CC) Manages network paths, called channels, between nodes in an OpenVMS Cluster. The CC level maintains channels by sending HELLO datagram messages between nodes. A node sends a HELLO datagram messages to indicate it is still functioning. The TR level uses channels to carry virtual circuit traffic. Datagram Exchange (DX) Interfaces to the LAN driver.
PI	Provides connections to LAN devices. PI represents LAN drivers and adapters over which packets are sent and received. PI Component Description LAN drivers Multiplex NISCA and many other clients (such as DECnet, TCP/IP, LAT, LAD/LAST) and provide them with datagram services on Ethernet and FDDI network interfaces. LAN adapters Consist of the LAN network driver and adapter hardware.

F.1.2 Paths Used for Communication

Table F-2 Communication Paths

Path	Description
Virtual circuit	A common transport that provides reliable port-to-port communication between OpenVMS Cluster nodes in order to: Ensure the delivery of messages without duplication or loss, each port maintains a virtual circuit with every other remote port. Ensure the sequential ordering of messages, virtual circuit sequence numbers are used on the individual packets. Each transmit message carries a sequence number; duplicates are discarded. The virtual circuit descriptor table in each port indicates the status of it's port-to-port circuits. After a virtual circuit is formed between two ports, communication can be established between SYSAPs in the nodes.
Channel	A logical communication path between two LAN adapters located on different nodes. Channels between nodes are determined by the pairs of adapters and the connecting network. For example, two nodes, each having two adapters, could establish four channels. The messages carried by a particular virtual circuit can be sent over any of the channels connecting the two nodes.

Note: The difference between a channel and a virtual circuit is that channels provide a path for datagram service. Virtual circuits, layered on channels, provide an error-free path between nodes. Multiple channels can exist between nodes in an OpenVMS Cluster but only one virtual circuit can exist between any two nodes at a time.

F.1.3 PEDRIVER

The port emulator driver, PEDRIVER, implements the NISCA protocol and establishes and controls channels for communication between local and remote LAN ports.

PEDRIVER implements a packet delivery service (at the TR level of the NISCA protocol) that guarantees the sequential delivery of messages. The messages carried by a particular virtual circuit can be sent over any of the channels connecting two nodes. The choice of channel is determined by the sender (PEDRIVER) of the message. Because a node sending a message can choose any channel, PEDRIVER, as a receiver, must be prepared to receive messages over any channel.

At any point in time, the TR level makes use of a single "preferred channel" to carry the traffic for a particular virtual circuit.

Reference: See Appendix G for more information about how transmit channels are selected.

F.2 Addressing LAN Communication Problems

Communication trouble in OpenVMS Cluster systems may be indicated by symptoms such as the following:

• Poor performance
• Console messages
  • "Virtual circuit closed" messages from PEA0 (PEDRIVER) on the console
  • "Connection loss" OPCOM messages on the console
  • CLUEXIT bugchecks
  • "Excessive packet losses on LAN Path" messages on the console
• Repeated loss of a virtual circuit or multiple virtual circuits over a short period of time (fewer than 10 minutes)

Before you initiate complex diagnostic procedures, do not overlook the obvious. Always make sure the hardware is configured and connected properly and that the network is started. Also, make sure system parameters are set correctly on all nodes in the OpenVMS Cluster.

F.2.2 Traffic Control

Keep in mind that an OpenVMS Cluster system generates substantially heavier traffic than other LAN protocols. In many cases, cluster behavior problems that appear to be related to the network might actually be related to software, hardware, or user errors. For example, a large amount of traffic does not necessarily indicate a problem with the OpenVMS Cluster network. The amount of traffic generated depends on how the users utilize the system and the way that the OpenVMS Cluster is configured with additional interconnects (such as DSSI and CI).

If the amount of traffic generated by the OpenVMS Cluster exceeds the expected or desired levels, then you might be able to reduce the level of traffic by:

• Adding DSSI or CI interconnects
• Shifting the user load between machines
• Adding LAN segments and reconfiguring the LAN connections across the OpenVMS Cluster system

	privacy and legal statement
4477PRO_030.HTML