Document revision date: 19 July 1999

Follow these steps to edit the LAVC$FAILURE_ANALYSIS.MAR program.

Step	Action
1	Copy the following files from SYS$EXAMPLES to your local directory: LAVC$FAILURE_ANALYSIS.MAR LAVC$BUILD.COM
2	Use the OpenVMS Cluster network map and the other information you collected to edit the copy of LAVC$FAILURE_ANALYSIS.MAR.

Example D-1 shows the portion of LAVC$FAILURE_ANALYSIS.MAR that you edit.

Example D-1 Portion of LAVC$FAILURE_ANALYSIS.MAR to Edit

; *** Start edits here *** ; Edit 1. ; ; Define the hardware components needed to describe ; the physical configuration. ; NEW_COMPONENT SYSTEM NODE NEW_COMPONENT LAN_ADP ADAPTER NEW_COMPONENT DEMPR COMPONENT NEW_COMPONENT DELNI COMPONENT NEW_COMPONENT SEGMENT COMPONENT NEW_COMPONENT NET_CLOUD CLOUD ; Edit 2. ; ; Diagram of a multi-adapter local area OpenVMS Cluster ; ; ; Sa -------+---------------+---------------+---------------+------- ; | | | | ; | MPR_A | | ; | .----+----. | | ; | 1| 1| 1| | ; BrA ALPHA BETA DELTA BrB ; | 2| 2| 2| | ; | `----+----' | | ; | LNI_A | | ; | | | | ; Sb -------+---------------+---------------+---------------+------- ; ; ; Edit 3. ; ; Label Node Description ; ----- ------ ----------------------------------------------- SYSTEM A, ALPHA, < - MicroVAX II; In the Computer room>... LAN_ADP A1, , <XQA; ALPHA - MicroVAX II; Computer room>,... LAN_ADP A2, , <XQB; ALPHA - MicroVAX II; Computer room>,... SYSTEM B, BETA, < - MicroVAX 3500; In the Computer room>... LAN_ADP B1, , <XQA; BETA - MicroVAX 3500; Computer room>,... LAN_ADP B2, , <XQB; BETA - MicroVAX 3500; Computer room>,... SYSTEM D, DELTA, < - VAXstation II; In Dan's office>... LAN_ADP D1, , <XQA; DELTA - VAXstation II; Dan's office>,... LAN_ADP D2, , <XQB; DELTA - VAXstation II; Dan's office>,... ; Edit 4. ; ; Label each of the other network components. ; DEMPR MPR_A, , <Connected to segment A; In the Computer room> DELNI LNI_A, , <Connected to segment B; In the Computer room> SEGMENT Sa, , <Ethernet segment A> SEGMENT Sb, , <Ethernet segment B> NET_CLOUD BRIDGES, , <Bridging between ethernet segments A and B> ; Edit 5. ; ; Describe the network connections. ; CONNECTION Sa, MPR_A CONNECTION MPR_A, A1 CONNECTION A1, A CONNECTION MPR_A, B1 CONNECTION B1, B CONNECTION Sa, D1 CONNECTION D1, D CONNECTION Sa, BRIDGES CONNECTION Sb, BRIDGES CONNECTION Sb, LNI_A CONNECTION LNI_A, A2 CONNECTION A2, A CONNECTION LNI_A, B2 CONNECTION B2, B CONNECTION Sb, D2 CONNECTION D2, D .PAGE ; *** End of edits ***

In the program, Edit number identifies a place where you edit the program to incorporate information about your network. Make the following edits to the program:

Location	Action
Edit 1	Define a category for each component in the configuration. Use the information from step 5 in Section D.5.1. Use the following format: NEW_COMPONENT component_type category Example: The following example shows how to define a DEMPR repeater as part of the component category: NEW_COMPONENT DEMPR COMPONENT
Edit 2	Incorporate the network map you drew for step 1 of Section D.5.1. Including the map here in LAVC$FAILURE_ANALYSIS.MAR gives you an electronic record of the map that you can locate and update more easily than a drawing on paper.
Edit 3	List each OpenVMS Cluster node and its LAN adapters. Use one line for each node. Each line should include the following information. Separate the items of information with commas to create a table of the information. Component type, followed by a comma. Label from the network map, followed by a comma. Node name (for SYSTEM components only). If there is no node name, enter a comma. Descriptive text that the network failure analysis program displays if it detects a failure with this component. Put this text within angle brackets (< >). This text should include the component's physical location. LAN hardware address (for LAN adapters). DECnet LAN address for the LAN adapter that DECnet uses.
Edit 4	List each of the other network components. Use one line for each component. Each line should include the following information: Component name and category you defined with NEW_COMPONENT. Label from the network map. Descriptive text that the network failure analysis program displays if it detects a failure with this component. Include a description of the physical location of the component. LAN hardware address (optional). Alternate LAN address (optional).
Edit 5	Define the connections between the network components. Use the CONNECTION macro and the labels for the two components that are connected. Include the following information: CONNECTION macro name First component label Second component label
Reference: You can find more detailed information about this exercise within the source module SYS$EXAMPLES:LAVC$FAILURE_ANALYSIS.MAR.

D.5.3 Assemble and Link the Program

Use the following command procedure to assemble and link the program:

$ @LAVC$BUILD.COM LAVC$FAILURE_ANALYSIS.MAR

Make the edits necessary to fix the assembly or link errors, such as errors caused by mistyping component labels in the path description. Assemble the program again.

D.5.4 Modify Startup Files

Before you execute the LAVC$FAILURE_ANALYSIS.EXE procedure, modify the startup files to run the procedure only on the node for which you supplied data.

Example: To execute the program on node OMEGA, you would modify the startup files in SYS$COMMON:[SYSMGR] to include the following conditional statement:

$ If F$GETSYI ("nodename").EQS."OMEGA" $ THEN $ RUN SYS$MANAGER:LAVC$FAILURE_ANALYSIS.EXE $ ENDIF

D.5.5 Execute the Program

To run the LAVC$FAILURE_ANALYSIS.EXE program, follow these steps:

Step	Action
1	Use an account that has the PHY_IO privilege.
2	Execute the program on each of the nodes that will perform the network failure analysis: $ RUN SYS$MANAGER:LAVC$FAILURE_ANALYSIS.EXE

After it executes, the program displays the approximate amount of nonpaged pool required for the network description. The display is similar to the following:

Non-paged Pool Usage: ~ 10004 bytes

D.5.6 Modify MODPARAMS.DAT

On each system running the network failure analysis, modify the file SYS$SPECIFIC:[SYSEXE]MODPARAMS.DAT to include the following lines, replacing value with the value that was displayed for nonpaged pool usage:

ADD_NPAGEDYN = value ADD_NPAGEVIR = value

Run AUTOGEN on each system for which you modified MODPARAMS.DAT.

D.5.7 Test the Program

Test the program by causing a failure. For example, disconnect a transceiver cable or ThinWire segment, or cause a power failure on a bridge, a DELNI interconnect, or a DEMPR repeater. Then check the OPCOM messages to see whether LAVC$FAILURE_ANALYSIS reports the failed component correctly. If it does not report the failure, check your edits to the network failure analysis program.

D.5.8 Display Suspect Components

When an OpenVMS Cluster network component failure occurs, OPCOM displays a list of suspected components. Displaying the list through OPCOM allows the system manager to enable and disable selectively the display of these messages.

The following are sample displays:

%%%%%%%%%%% OPCOM 1-JAN-1994 14:16:13.30 %%%%%%%%%%% (from node BETA at 1-JAN-1994 14:15:55.38) Message from user SYSTEM on BETA LAVC-W-PSUSPECT, component_name %%%%%%%%%%% OPCOM 1-JAN-1994 14:16:13.41 %%%%%%%%%%% (from node BETA at 1-JAN-1994 14:15:55.49) Message from user SYSTEM on BETA %LAVC-W-PSUSPECT, component_name %%%%%%%%%%% OPCOM 1-JAN-1994 14:16:13.50 %%%%%%%%%%% (from node BETA at 1-JAN-1994 14:15:55.58) Message from user SYSTEM on BETA %LAVC-I-ASUSPECT, component_name

The OPCOM display of suspected failures uses the following prefixes to list suspected failures:

• %LAVC-W-PSUSPECT---Primary suspects
• %LAVC-I-ASUSPECT---Secondary or additional suspects
• %LAVC-S-WORKING---Suspect component is now working

The text following the message prefix is the description of the network component you supplied when you edited LAVC$FAILURE_ANALYSIS.MAR.

In addition to the sample programs described in Appendix D, a number of subroutines are provided as a way of extending the capabilities of the sample programs. Table E-1 describes the subroutines.

Table E-1 Subroutines for LAN Control

Subroutine	Description
To manage LAN adapters:
SYS$LAVC_START_BUS	Directs PEDRIVER to start the NISCA protocol on a specific LAN adapter.
SYS$LAVC_STOP_BUS	Directs PEDRIVER to stop the NISCA protocol on a specific LAN adapter.
To control the network failure analysis system:
SYS$LAVC_DEFINE_NET_COMPONENT	Creates a representation of a physical network component.
SYS$LAVC_DEFINE_NET_PATH	Creates a directed list of network components between two network nodes.
SYS$LAVC_ENABLE_ANALYSIS	Enables the network failure analysis, which makes it possible to analyze future channel failures.
SYS$LAVC_DISABLE_ANALYSIS	Stops the network failure analysis and deallocates the memory used for the physical network description.

E.1.1 Purpose of the Subroutines

The subroutines described in this appendix are used by the the LAN control programs, LAVC$FAILURE_ANALYSIS.MAR, LAVC$START_BUS.MAR, and LAVC$STOP_BUS.MAR. Although these programs are sufficient for controlling LAN networks, you may also find it helpful to use the LAN control subroutines to further manage LAN adapters.

E.2 Starting the NISCA Protocol

The SYS$LAVC_START_BUS subroutine starts the NISCA protocol on a specified LAN adapter. To use the routine SYS$LAVC_START_BUS, specify the following parameter:

Parameter	Description
BUS_NAME	String descriptor representing the LAN adapter name buffer, passed by reference. The LAN adapter name must consist of 15 characters or fewer.

Example: The following Fortran sample program uses SYS$LAVC_START_BUS to start the NISCA protocol on the LAN adapter XQA:

PROGRAM START_BUS EXTERNAL SYS$LAVC_START_BUS INTEGER*4 SYS$LAVC_START_BUS INTEGER*4 STATUS STATUS = SYS$LAVC_START_BUS ( 'XQA0:' ) CALL SYS$EXIT ( %VAL ( STATUS )) END

E.2.1 Status

The SYS$LAVC_START_BUS subroutine returns a status value in register R0, as described in Table E-2.

Table E-2 SYS$LAVC_START_BUS Status

Status	Result
Success	Indicates that PEDRIVER is attempting to start the NISCA protocol on the specified adapter.
Failure	Indicates that PEDRIVER cannot start the protocol on the specified LAN adapter.

E.2.2 Error Messages

SYS$LAVC_START_BUS 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 argument list No access to the LAN adapter name buffer descriptor No access to the LAN adapter name buffer
SS$_DEVACTIVE	Bus already exists. PEDRIVER is already trying to use this LAN adapter for the NISCA protocol.
SS$_INSFARG	Not enough arguments supplied.
SS$_INSFMEM	Insufficient nonpaged pool to create the bus data structure.
SS$_INVBUSNAM	Invalid bus name specified. The device specified does not represent a LAN adapter that can be used for the protocol.
SS$_IVBUFLEN	This status value is returned under the following conditions: The LAN adapter name contains no characters (length = 0). The LAN adapter name contains more than 15 characters.
SS$_NOSUCHDEV	This status value is returned under the following conditions: The LAN adapter name specified does not correspond to a LAN device available to PEDRIVER on this system. No LAN drivers are loaded in this system; the value for NET$AR_LAN_VECTOR is 0. PEDRIVER is not initialized; PEDRIVER's PORT structure is not available. Note: By calling this routine, an error-log message may be generated.
SS$_NOTNETDEV	PEDRIVER does not support the specified LAN device.
SS$_SYSVERDIF	The specified LAN device's driver does not support the VCI interface version required by PEDRIVER.

PEDRIVER can return additional errors that indicate it has failed to create the connection to the specified LAN adapter.

E.3 Stopping the NISCA Protocol

The SYS$LAVC_STOP_BUS routine stops the NISCA protocol on a specific LAN adapter.

Caution: Stopping the NISCA protocol on all LAN adapters causes satellites to hang and could cause cluster systems to fail with a CLUEXIT bugcheck.

To use this routine, specify the parameter described in the following table.

Parameter	Description
BUS_NAME	String descriptor representing the LAN adapter name buffer, passed by reference. The LAN adapter name must consist of 15 characters or fewer.

Example: The following Fortran sample program shows how SYS$LAVC_STOP_BUS is used to stop the NISCA protocol on the LAN adapter XQB:

PROGRAM STOP_BUS EXTERNAL SYS$LAVC_STOP_BUS INTEGER*4 SYS$LAVC_STOP_BUS INTEGER*4 STATUS STATUS = SYS$LAVC_STOP_BUS ( 'XQB' ) CALL SYS$EXIT ( %VAL ( STATUS )) END

E.3.1 Status

The SYS$LAVC_STOP_BUS subroutine returns a status value in register R0, as described in Table E-3.

Table E-3 SYS$LAVC_STOP_BUS Status

Status	Result
Success	Indicates that PEDRIVER is attempting to shut down the NISCA protocol on the specified adapter.
Failure	Indicates that PEDRIVER cannot shut down the protocol on the specified LAN adapter. However, PEDRIVER performs the shutdown asynchronously, and there could be other reasons why PEDRIVER is unable to complete the shutdown.

When the LAVC$STOP_BUS module executes successfully, the following device-attention entry is written to the system error log:

DEVICE ATTENTION... NI-SCS SUB-SYSTEM... FATAL ERROR DETECTED BY DATALINK...

In addition, the following hexadecimal values are written to the STATUS field of the entry:

• First longword (00000001)
• Second longword (00001201)

This error-log entry indicates expected behavior and can be ignored. However, if the first longword of the STATUS field contains a value other than hexadecimal value 00000001, an error has occurred and further investigation may be necessary.

E.3.2 Error Messages

SYS$LAVC_STOP_BUS 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 argument list No access to the LAN adapter name buffer descriptor No access to the LAN adapter name buffer
SS$_INVBUSNAM	Invalid bus name specified. The device specified does not represent a LAN adapter that can be used for the NISCA protocol.
SS$_IVBUFLEN	This status value is returned under the following conditions: The LAN adapter name contains no characters (length = 0). The LAN adapter name has more than 15 characters.
SS$_NOSUCHDEV	This status value is returned under the following conditions: The LAN adapter name specified does not correspond to a LAN device that is available to PEDRIVER on this system. No LAN drivers are loaded in this system. NET$AR_LAN_VECTOR is zero. PEDRIVER is not initialized. PEDRIVER's PORT structure is not available.

E.4 Creating a Representation of a Network Component

The SYS$LAVC_DEFINE_NET_COMPONENT subroutine creates a representation for a physical network component.

Use the following format to specify the parameters:

STATUS = SYS$LAVC_DEFINE_NET_COMPONENT (
component_description,
nodename_length,
component_type,
lan_hardware_addr,
lan_decnet_addr,
component_id_value )

Table E-4 describes the SYS$LAVC_DEFINE_NET_COMPONENT parameters.

Table E-4 SYS$LAVC_DEFINE_NET_COMPONENT Parameters

Parameter	Description
component_description	Address of a string descriptor representing network component name buffer. The length of the network component name must be less than or equal to the number of COMP$C_MAX_NAME_LEN characters.
nodename_length	Address of the length of the node name. This address is located at the beginning of the network component name buffer for COMP$C_NODE types. You should use zero for other component types.
component_type	Address of the component type. These values are defined by $PEMCOMPDEF, found in SYS$LIBRARY:LIB.MLB.
lan_hardware_addr	Address of a string descriptor of a buffer containing the component's LAN hardware address (6 bytes). You must specify this value for COMP$C_ADAPTER types. For other component types, this value is optional.
lan_decnet_addr	String descriptor of a buffer containing the component's LAN DECnet address (6 bytes). This is an optional parameter for all component types.
component_id_value	Address of a longword that is written with the component ID value.

	privacy and legal statement
4477PRO_029.HTML