4.1 Introduction

4.2 Accessing Configuration Data

4.2.1 Opening a Managed Object for Editing

4.2.2 Getting Keywords and Qualifiers

4.2.3 Setting a Keyword Value

4.2.4 Closing a Managed Object

4.3 Keywords and Values

4.3.1 Qualifiers

4.3.2 Basic Keywords

4.3.3 Array Keywords

4.3.4 Struct Keywords

4.3.5 StructAndArray Keywords

4.4 Keyword Enumeration

4.4.1 Enumerating the Top-Level Keywords

4.4.2 Array Keyword Enumeration

4.4.3 Struct Keyword Enumeration

4.4.4 StructAndArray Keyword Enumeration

4.5 Importing and Exporting Configuration Data

4.5.1 Exporting a Configuration

4.5.2 Importing a Configuration

4.1 Introduction

Within the NMS OAM configuration database, a record of configuration information exists for each managed object. The Supervisor component of the OAM service manages the database. Client applications can add, delete, or modify this information.

This chapter describes how configuration data is stored in the configuration database, and how to access and change configuration information.

Note: The oamsys and oamcfg utilities included with the NMS OAM software provide a convenient way to access and modify configuration information in the managed objects in the NMS OAM database. For more information about NMS OAM utilities, refer to the NMS OAM System User's Manual.

4.2 Accessing Configuration Data

To access configuration data for a managed object, a client application:

1. Opens the managed object.

2. Retrieves keyword values or qualifiers, or sets values as necessary.

3. Closes the managed object.

4.2.1 Opening a Managed Object for Editing

To access configuration data for a managed object, a client application opens the object using oamOpenObject. With this function invocation, the application supplies:

• The context handle to the OAM service.

• The name of the managed object. This name is not case-sensitive.

• The opening mode. Valid modes are:

  Mode	Description
  OAM_READONLY	Opens the object for reading only. The application cannot change keyword values.
  OAM_READWRITE	Opens the object for reading and writing. The application can change the values of read/write keywords. A managed object cannot be opened in this mode if any other client application has it currently opened.

  If a client application attempts to open a managed object for writing, and the object is currently opened by another application, oamOpenObject fails and OAMERR_ACCESS_DENIED is returned to the application.
  A managed object can be opened in read-only mode (OAM_READONLY) even if it is currently opened in read-only mode by another application.
  An open managed object cannot be deleted by any application other than the application that opened the object.

If the object opening attempt succeeds, oamOpenObject returns a handle to the object, to be used with subsequent editing functions.

4.2.2 Getting Keywords and Qualifiers

All configuration data in the configuration database is represented and communicated as keyword name/value pairs:

keyword=value

Example: AutoStart=YES

This approach is used for every configurable feature of every managed component, including boards, extended management components such as Hot Swap, and the Supervisor itself.

Each keyword has several attributes, called qualifiers. For example, the qualifier Type indicates the type of value it accepts (Integer, String, etc.). The qualifier ReadOnly indicates if a keyword is read-only. Qualifiers are not case-sensitive.

Once an object has been opened using oamOpenObject, a client application can retrieve values for the object's keywords using oamGetKeyword. oamGetKeyword takes a keyword name. (This name is not case-sensitive.) If the function invocation is successful, oamGetKeyword returns a buffer containing the string value of the keyword.

A client application can retrieve the value of a keyword qualifier using oamGetQualifier. If the function invocation is successful, oamGetQualifier returns a buffer containing the value of the specified keyword qualifier.

4.2.3 Setting a Keyword Value

Once an object has been opened using oamOpenObject, a client application can set the value of a keyword using oamSetKeyword. The object must have been opened in OAM_READWRITE mode. If the function invocation is successful, oamSetKeyword returns SUCCESS.

Most keyword settings are committed when you close the managed object (as described in Section 4.2.4). However, actual operation may not be affected until you restart the board. For details, see your board-specific documentation.

4.2.4 Closing a Managed Object

To close a managed object, a client application invokes oamCloseObject. If the function invocation is successful, the object is closed. If the object was opened in read/write mode, any changes are validated and saved. If the object being closed was opened in read-only mode, it remains open from the point of view of any other application.

4.3 Keywords and Values

Keywords are not case-sensitive. All values are strings, or strings that represent integers. An integer keyword may have a fixed numeric range of legal values. A string keyword may support a fixed set of legal values, or may accept any string.

There are eight different keyword types. The type of a particular keyword can be determined by retrieving its Type qualifier (see Section 4.3.1). The following table lists and describes each keyword type:

This keyword type...	Indicates that the keyword represents...
Integer	A string representing an integer value. For example: 12
String	A string value.
Array	An array of multiple values.
Struct	A struct containing multiple keywords and values.
StructAndArray	Both a struct with multiple keywords, and an array of values.
Filename	A filename (string). For example: readme.txt
Object	A managed object name (string). For example: Supervisor
IPAddress	An IP address (string). For example: 255:255:255:0

4.3.1 Qualifiers

The following table lists the currently supported qualifiers.

Qualifier	Description	Valid Values
Type	Type of keyword value (see Section 4.3.3).	Integer, String, Array, Struct, StructAndArray, Filename, Object, IPAddress
ReadOnly	Indicates if keyword value is read-only or not.	No indicates keyword value is read/write. Yes, or no value at all, indicates keyword value is read-only.
Base	Mathematical base of integer. For example, 16 for a hexadecimal number.	Any integer
Min	If type is Integer, indicates the minimum allowed value.	Any integer
Max	If type is Integer, indicates the maximum allowed value.	Any integer
Choices	Represents an array containing a list of valid values for the keyword. For read/write keywords only.	Array
Choices.Count	Indicates the number of valid keyword values in array Choices. Zero-based.	Any positive integer
Choices[x]	Represents value of item x in array Choices. x is an integer between 0 and (Choices.Count - 1)	Any string
Description	Text description of keyword	Any string (80 chars or less)
Keywords	Represents an array containing a list of keywords contained within a Struct keyword (see Section 4.3.3).	Array
Keywords.Count	Indicates the number of keywords contained in array Keywords. Zero-based.	Any positive integer
Keywords[x]	Represents keyword x in array keyword Keywords. x is an integer between 0 and (Keywords.Count - 1)	Any keyword

4.3.2 Basic Keywords

Basic keyword types String, Integer, Filename, Object, and Address all represent string values. For an Integer keyword, the Min and Max qualifiers may indicate a minimum and maximum allowed value. The Base qualifier may indicate the mathematical base of the value (for example, base 16 for hexadecimal numbers). For all other basic keyword types, the Choices qualifier may indicate a list of valid values.

4.3.3 Array Keywords

Certain values are organized into arrays. Each array is represented by a keyword of type Array. For an Array keyword, the following syntax is used:

Syntax	Description
keyword[item#]	Represents item item# in array keyword keyword. Arrays are zero-based. For example, if the first item assigned to array keyword DSPFile is file1.dsp, and the second item in the array is file2.dsp, then DSPFile[0]=file1.dsp and DSPFile[1]=file2.dsp.
keyword.Count	Read-only keyword indicating the number of items assigned to array keyword keyword. For example, if there are five items assigned to array keyword DSPFile, then DSPFile.Count=5.

If keyword.Count is 0, the array is empty. You can set an element of an empty array to a value, implicitly causing allocation of space within the database record. For example, if the default configuration for a board lists no TCP files, then invoking oamGetKeyword with the keyword TCPFiles.Count returns 0. However, you can set TCPFiles[0] to a value (such as nocc). Then when you invoke oamGetKeyword again for the keyword TCPFiles.Count, the function returns 1.

The Array keyword itself does not represent a value. For example, if oamGetKeyword is performed for keyword DSPFile (without an index), the error OAMERR_NOT_FOUND is returned.

4.3.4 Struct Keywords

Many keyword/value pairs are organized into groups called structs (as in the C language). Keywords within the struct have related functionality. Each struct has a name. The keyword name for each keyword in the struct consists of the struct name followed by a period (.) and then the keyword (see Figure 11). The struct name within each keyword name is a Struct keyword.

Figure 11. Struct Keyword Names

Structs can contain structs. In the following example, struct Clocking contains structs Hbus and MVIP:

Clocking.HBus.ClockMode = MASTER_A
Clocking.HBus.AutoFallBack = YES
Clocking.MVIP.ClockRef = SEC8K
Clocking.MVIP.AutoFallBack = NO

In this example, Clocking, Hbus, and MVIP are Struct keywords.

Structs can contain arrays. For example, struct NetworkInterface contains array T1E1[x]. This is notated as NetworkInterface.T1E1[x].

An array can contain multiple instances of a struct, each containing an identical set of member keyword/value pairs. For example, Resource[x] is an array containing multiple instances of struct Resource. Resource contains several members, some of which are arrays:

Resource[0].Name = RSC1
Resource[0].Size = 120
Resource[0].FileName[0] = myfile.foo
Resource[0].FileName[1] = myfile2.foo
Resource[0].SpanEnable=AUTO
Resource[1].Name = RSC1
Resource[1].Size = 60
Resource[1].FileName[0] = myfile.foo
Resource[1].SpanEnable=AUTO

For any Struct keyword, the qualifier Keywords represents an array containing a list of keywords contained within the Struct keyword. For example, for the Resource[x] keyword:

• The qualifier Keywords[1] yields "Name"

• The qualifier Keywords[2] yields "Size"

• The qualifier Keywords[3] yields "FileName"

• The qualifier Keywords[4] yields "SpanEnable"

The qualifier Keywords.Count indicates the number of keywords in the Struct keyword. This value is zero-based. For example, for the Resource[x] keyword, Keywords.Count yields 3.

The Struct keyword itself does not represent a value. If oamGetKeyword is performed for a keyword that is of type Struct, the error OAMERR_NOT_FOUND is returned.

4.3.5 StructAndArray Keywords

A StructAndArray keyword represents both a struct and an array. As a hypothetical example, struct Trunks contains one member keyword, GlobalParm, whose value is a global parameter string. Also, array Trunks[x] contains a specific parameter string, SpecificParm, for trunk x.

Just as with Array keywords, the keyword name xxx.Count indicates the number of items assigned to array keyword xxx. Also, as with Struct keywords, the qualifier Keywords for a StructAndArray keyword represents an array containing a list of keywords within the struct. The qualifier Keywords.Count indicates the number of keywords in the struct.

The StructAndArray keyword itself does not represent a value. If oamGetKeyword is performed for a keyword that is of type StructAndArray, the error OAMERR_NOT_FOUND is returned.

4.4 Keyword Enumeration

An application can discover the set of keywords in a database record. By querying the type and certain qualifiers of each keyword, the application can obtain sufficient information to further process the keyword. If a keyword represents a data structure (such as a struct or array), the application can determine the keywords within the data structure. By executing this process recursively, all values of all keywords of a managed object can be discovered. This process is called keyword enumeration.

The following sections describe how to enumerate different keyword types. The demonstration program oaminfo included with the NMS OAM software illustrates the keyword enumeration process. See Chapter 10 for more information about oaminfo.

4.4.1 Enumerating the Top-Level Keywords

To enumerate the keywords for a managed object, first retrieve the top-level keywords. Then explore each keyword to determine the keywords it contains. Then explore those keywords, and so on.

All top-level keywords for a managed object are contained within a single struct with no name. To retrieve the top-level keywords for a managed object:

1. Get the number of keywords in the no-name struct. To do so, invoke oamGetQualifier, specifying "" as the keyword, and Keywords.Count as the attribute to retrieve. oamGetQualifier returns the number of keywords in the struct.

2. To determine the names of each of the keywords within the struct, invoke oamGetQualifier repeatedly, each time specifying "" as the keyword, and Keywords[x] as the attribute to retrieve. oamGetQualifier returns a single keyword with each invocation.

4.4.2 Array Keyword Enumeration

To determine how many elements are contained in an array, use oamGetKeyword to get the value of keyword keyword.Count. For example, to determine how many elements are in array DSPfile, invoke oamGetKeyword as follows:

oamGetKeyword( hObj, "DSPfile.Count", info, sizeof(info) );
sscanf( info, "%d",numElements )

You can then get each specific value x by invoking oamGetKeyword on keyword[x]:

oamGetKeyword( hObj, "DSPfile[1]", info, sizeof(info) );

If the returned value is a keyword, you can determine its Type attribute and perform further analysis and processing of the keyword.

4.4.3 Struct Keyword Enumeration

To determine how many keywords are contained within a struct, invoke oamGetQualifier on the Keywords.Count qualifier for the Struct keyword. For example, to get the number of keywords in struct Driver, use oamGetQualifier as follows:

oamGetQualifier( hObj, "Driver", "Keywords.Count", info, sizeof(info) );
sscanf( info, "%d",numElements )

To then determine the names of each of the keywords within the struct, use the qualifier Keywords[x]. For example:

for ( i  = 0; i < numFields; i++ )
{
  char field[ 100 ];

  sprintf( field, "Keywords[%d]", i );
  oamGetQualifier(( ...., "Driver", field,  ....  );
}

The attribute string returned is in the form: keyword.keyword (for example, "Driver.Name"). By subsequently determining the Type attribute of the returned keyword name, you can perform further analysis and processing of the contents of the struct.

4.4.4 StructAndArray Keyword Enumeration

To perform keyword enumeration for a StructAndArray keyword, first perform keyword enumeration treating it as an Array keyword (as described in Section 4.3.3). This process enumerates the elements in the array represented by the keyword. Then perform keyword enumeration treating it as a Struct keyword to enumerate the elements in the struct the keyword represents. By subsequently determining the Type attributes of each returned keyword name, you can perform further analysis and processing of the contents of the structs or arrays.

4.5 Importing and Exporting Configuration Data

You can export the contents of the configuration database to a file, and then import the file into the configuration database on another system. This feature is useful for setting up multiple identical systems.

Note: Only the entire contents of a configuration database can be exported. Importing a database file completely obliterates and replaces all data in an existing database.

4.5.1 Exporting a Configuration

To export the contents of a configuration database:

• All client applications should close any managed objects currently open for writing. Otherwise, any pending changes are not included in the exported data.

• A client application invokes oamConfigExport, passing it an output filename.

oamConfigExport exports a snapshot of the entire configuration to the specified output file.

Note: Do not modify the output file. It is for use by the OAM service only.

4.5.2 Importing a Configuration

To import the contents of a configuration database from a file:

• Client applications close all open managed objects.
  This is necessary because the current configuration will be completely overwritten and all current data will be lost.

• A client application invokes oamConfigImport, passing it the name of a file exported as described in Section 4.5.1.

oamConfigImport imports the entire configuration from the specified input file. The current configuration is lost and is replaced by the new configuration. All plug-ins are restarted.

Note: Applications registered for alert notification before the configuration is imported remain registered after the import is complete.