5.1 Introduction

5.2 Identifying Boards

5.3 Retrieving Board Information

5.3.1 Retrieving the Name of a Board

5.3.2 Retrieving Other Board Information

5.4 Managing Board Information

5.4.1 Creating Board Managed objects

5.4.2 Deleting Board Managed Objects

5.4.3 Automatically Detecting Installed Boards

5.5 Starting, Stopping, and Testing Boards

5.5.1 Starting Boards

5.5.2 Testing Boards

5.5.3 Stopping Boards

5.1 Introduction

This chapter describes how to:

• Retrieve information about boards in a system.

• Manage information about boards in the configuration database.

• Start, test, and stop boards using the OAM service.

5.2 Identifying Boards

In the NMS OAM system, each board is referenced using the following identifiers (see Figure 12):

Identifier	Description
Board name	This is the primary way to identify each board in an NMS OAM system. A default board name for each board is created when the board is added to the system. This name can be changed by opening the board managed object and modifying the Name keyword. You can use the board name to gain other information about a board. For details, see Section 5.3.
Board number	This is the typical way to identify a board in most NMS software products. Each board in a chassis has a unique board number. A default board number for each board is created when the board is added to the system. This number can be changed by opening the board managed object and modifying the Number keyword.
PCI bus and slot	You can identify a board by its unique PCI bus and slot location.

The following secondary ID information is also available:

Identifier	Description
A driver name/driver board ID combination	The driver name is unique among all driver names in the system. The driver board ID is unique among all boards accessed by a given driver. However, two boards accessed by different drivers may have the same driver board ID. The driver name/driver board ID together make up an ID for the board which is unique within the system.
A serial number	This number is factory-configured, and may not be present for all boards.

Figure 12. Board Identification Options

5.3 Retrieving Board Information

The primary way to identify each board to NMS OAM is by its board name. As shown in Figure 13, several functions are provided in the NMS OAM API to retrieve information about a board, given a board name. If the name is not known, other functions are provided to retrieve the name of a board based on other information about the board.

Figure 13. Board Name

5.3.1 Retrieving the Name of a Board

To retrieve the name of a board from the configuration database, use any of the following board information:

• PCI bus and slot

• Driver ID number

• Number

• Serial number

• Product type
  Note: Not all of this information may be available for a given board.

Pass this information to the appropriate oamBoardLookupByXXX function, along with the context handle to the OAM service. The function returns a buffer containing the name of the board.

You can retrieve the names of all boards in the database, using the oamBoardEnum function. With the function invocation, pass an index value, starting at 0 and continuing until the function returns OAMERR_NOT_FOUND. A board name is returned with each invocation.

For more information about these functions, refer to Chapter 9.

5.3.2 Retrieving Other Board Information

Once you have retrieved the name of a board (as described in Section 5.3.1), you can retrieve any other information about the board using the appropriate oamBoardGetXXX function. Pass the name of the board to this function, along with the context handle to the OAM service.

For more information about each function, refer to Chapter 9.

5.4 Managing Board Information

Using the OAM service, a client application can:

• Create board managed objects.

• Delete board managed objects.

• Detect and add boards physically installed in a system (this is not supported by all board plug-ins).

5.4.1 Creating Board Managed objects

A client application can create managed objects for boards, even if the board is not yet physically installed in the system. Once a board has a managed object, it can be configured. For more information about configuring managed objects, refer to Chapter 4.

To create a board managed object, use oamCreateBoard. Pass the following information in the function invocation:

• The context handle to the OAM service.

• The product type for the board. When the Supervisor starts up, it queries all of the installed plug-ins for the names of all product types that they support. These names are stored in the Supervisor array keyword Products[x].
  Note: If a plug-in for a board family is not installed, product type names for the boards in the family are not available, and no boards of the family can be created or accessed.

If the function succeeds, a new managed object is created. A record for the managed object is created in the NMS OAM database, containing default keyword settings. A default name and board number are generated for the board:

Board ID	Default
Name	The product type and an integer. For example: CG_6000C_QUAD 0
Number	The next available number greater than or equal to 0.

The board name is passed back in the function call. The name is added to the list of board names in the Supervisor keyword Boards[x].

You can retrieve the board number using any oamBoardLookupByXXX function, as described in Section 5.3.

The board name and board number can be changed by modifying the Name or Number keywords for the board managed object. To learn how to modify keywords, refer to Chapter 4.

5.4.2 Deleting Board Managed Objects

A client application can delete managed objects for boards, using oamDeleteBoard. To use this function, pass the context handle to the OAM service, and the name of the board to delete. Specify NULL to delete all boards.

A client application cannot delete a managed object if it is currently opened by another application.

Note: To delete a board, the board must exist as a managed object.

5.4.3 Automatically Detecting Installed Boards

The OAM service can detect hardware physically installed in a chassis, and create a managed object for each detected board.

Note: Some plug-ins do not support this operation.

To detect and add boards:

1. A client application invokes the oamDetectBoards function.
   This function detects the boards, generates a board name for each board, and adds each name to the Supervisor keyword DetectedBoards[x].
   Note: This function does not actually add board configuration information to the configuration database; it simply collects board names.
   The list of detected boards includes all boards physically installed in the system, including boards that already have managed objects.

2. The client application invokes oamAddDetectedBoard for each detected board to create a managed object for the board.
   oamAddDetectedBoard adds a complete configuration for the board to the database. It also copies the specified board name from the Supervisor keyword DetectedBoards[x] to the Supervisor keyword Boards[x].

5.5 Starting, Stopping, and Testing Boards

This section describes how to start, stop, and test boards using the NMS OAM service.

5.5.1 Starting Boards

A board must exist as a managed object before you can start it using the NMS OAM service.

Use the function oamStartBoard to start a board. With the function invocation, pass the context handle to the OAM service, and the name of the board to start. Pass NULL as the name to start all boards in parallel.

oamStartBoard is an asynchronous function: it sends a return code to the application indicating if it was successfully initiated. If the return value is SUCCESS, the actual results of the board starting attempt arrive later as events. As the Supervisor attempts to start each board, it returns an OAMEVN_STARTBOARD_DONE event to the application. The value field returned with the event indicates if the board started successfully:

• OAM_REASON_FINISHED indicates that the board started successfully.

• OAM_REASON_FAILED indicates that the board starting attempt failed.

Further information may be available in the OAM_MSG message buffer (text portion), as well as in other alert notifications that may have been generated during the start process.

5.5.2 Testing Boards

Once a board is started, a client application can test it and report results.

Note: Some board models do not support testing. To determine if a board model supports testing, refer to the board documentation.

Use the function oamTestBoard to test one or more boards. With the function invocation, pass the context handle to the OAM service, and the name of the board to test. Pass NULL as the name to test all boards in parallel.

oamTestBoard is an asynchronous function: it sends a return code to the application indicating if it was successfully initiated. If the return value is SUCCESS, the actual results of the board test attempt arrive later as events. As the Supervisor attempts to test each board, it returns an OAMEVN_TESTBOARD_DONE event to the application. The value field returned with the event indicates if the board tested successfully:

• OAM_REASON_FINISHED indicates that the board tested successfully.

• OAM_REASON_FAILED indicates that the board test attempt failed.

In either case, further information may be available in the OAM_MSG message buffer (text portion), as well as in other alert notifications that may have been generated during the test attempt.

5.5.3 Stopping Boards

A client application can stop (shut down) any started board accessible as an OAM service managed object.

Use the function oamStopBoard to cause one or more boards to stop. With the function invocation, pass the context handle to the OAM service, and the name of the board to stop. Pass NULL as the name to stop all boards.

oamStopBoard is an aynchronous function: it sends a return code to the application indicating if it was successfully initiated. If the return value is SUCCESS, the actual results of the board stop attempt arrive later as events. As the Supervisor attempts to stop each board, it returns an OAMEVN_STOPBOARD_DONE event to the application. The value field returned with the event indicates if the board was stopped successfully:

• OAM_REASON_FINISHED indicates that the board was stopped successfully.

• OAM_REASON_FAILED indicates that the board stop attempt failed.

In either case, further information may be available in the OAM_MSG message buffer (text portion), as well as in other alert notifications that may have been generated during the board stop attempt.

Note: oamStopBoard causes boards to stop immediately, regardless of any tasks they are currently performing. To avoid problems, make sure that a board is idle before stopping it.