6.1 Introduction

6.2 oamcfg Reference

6.2.1 Launching oamcfg

6.2.2 Command Line Options

6.3 oamcfg Procedures

6.3.1 Displaying Board Product Types

6.3.2 Creating a Board Managed Object

6.3.3 Deleting a Board Managed Object

6.3.4 Displaying Board ID Information

6.3.5 Changing Keyword Settings

Specifying Settings in Keyword Files

Specifying Settings on the Command Line

6.3.6 Changing Board ID Information

6.3.7 Replacing Existing Data

6.3.8 Starting Boards

6.3.9 Stopping Boards

6.3.10 Testing Boards

6.4 Multi-Operation Invocations

6.5 Order of Operation

6.1 Introduction

This chapter:

• Documents oamcfg command line options and syntax

• Provides procedures for performing various operations using oamcfg

6.2 oamcfg Reference

The OAM configuration utility, oamcfg, allows you to perform the following operations:

• Add, change, or delete keywords for managed objects, based upon information supplied in keyword files.

• Create and delete board managed objects in the OAM database.

• Start (boot) one or more boards.

• Stop (shut down) boards.

• Test boards (if supported by board plug-in).

• Display basic ID information for each board.

You can direct oamcfg to perform a given operation on a single managed object. Alternatively, the utility can configure all board managed objects in a single invocation.

Note: To use oamcfg, ctdaemon must be running. To learn how to start ctdaemon, refer to Chapter 4.

6.2.1 Launching oamcfg

To launch oamcfg, enter oamcfg on the command line, followed by zero or more command line options. Precede each option with a hyphen (-) or slash (/). If the option includes data, specify the data directly after the option on the command line. Valid options are described in Section 6.2.2.

If you invoke oamcfg without command line options, it displays its help screen and terminates.

6.2.2 Command Line Options

This section describes oamcfg command line options.

Use the -b, -l, and/or -n options to specify a board or other managed object for the operation(s). If you do not specify a board or managed object with these options, the specified operation(s) are performed for all board managed objects.

Option	Description
-?	Causes oamcfg to display its help screen, and terminate.
-b brdno	Specifies the board number of the board to perform the specified operation(s) for. If this option, and the -l and -n options are omitted, the specified operation(s) are performed for all board managed components. You can use this option to change the board number of the board managed component. For details, see Section 6.3.6.
-c product	Creates a managed object for the specified board type product. Also creates a record in the OAM configuration database for the board, containing basic board ID information. product is the product string for the board type. If product is: ? ... oamcfg displays a list of all product types supported by the installed plug-ins, in alphabetical order, and then terminates. If product is: " " ... oamcfg chooses the first product name in this list.
-d	Deletes the managed object(s) for the specified board(s). Also deletes the record(s) for the board(s) from the OAM configuration database.
-f cfgfile	Adds the information from keyword file cfgfile to the database record(s) for the specified managed object(s). This option can appear more than once on a command line, to load multiple files. Statements in the keyword file override information already in the record. Note: oamcfg is designed to parse keyword files, not system configuration files such as those that oamsys takes as input. Also, oamcfg cannot parse AG configuration files designed for agmon.
-h	Causes oamcfg to display its help screen, and terminate.
-i	Used with the -p, -s, and -t options. Causes oamcfg to return immediately. By default, oamcfg does not return until it receives indications that its operations have completed (successfully or not). Use the -i option if you wish to avoid this and return immediately.
-k keyword=value	Sets keyword keyword to value value in the database record for the specified managed object. This option can appear more than once on a command line, to set multiple keywords.
-l bus:slot	Specifies the location (PCI bus and slot) of the board to perform the specified operation(s) for. If this option, and the -b and -n options are omitted, the specified operation(s) are performed for all board managed objects. You can use this option to change the bus and slot location specified in the database for a board. For details, see Section 6.3.6.
-n brdname	Specifies the name of the managed object to perform the specified operation(s) for. This can be the name of a board, or another managed component (such as an EMC, or the Supervisor). If this option, and the -l and -b options are omitted, the specified operation(s) are performed for all board managed objects. You can use this option to change the name of a board managed object. For details, see Section 6.3.6.
-p	Stops (shuts down) the specified board(s). Note: The board stops immediately, interrupting any ongoing process. To avoid problems, make sure a board is not performing any operations before stopping it.
-q	Causes oamcfg to query the OAM configuration database for the board ID information for the specified board(s).
-r	Used whenever configuration data in the OAM database is being changed (that is., the -f or -k option is used, or board ID information is changed). Causes oamcfg to reset to their default values all keywords (except board ID information) for the specified managed object(s). oamcfg then makes the specified changes. If the -r option is omitted, oamcfg adds or replaces keyword values specified in the keyword file without disturbing any other settings.
-s	Starts (boots) the specified board(s).
-t testopts	Tests the specified board(s), if supported by the board plug-in. testopts is a numeric value indicating how to perform the test. For specifics about this operation, refer to your board documentation.

6.3 oamcfg Procedures

The following sections provide procedures for several oamcfg operations.

6.3.1 Displaying Board Product Types

When specifying board configuration information in a system configuration file, you must supply the product type for each board: a string which identifies the board type to OAM.

Different board plug-ins support different board types. To determine what strings to specify for your boards, you can query OAM for the board types supported by the installed plug-ins. To do so, enter:

oamcfg -c?

oamcfg returns a list of available board product types. Each listed product type is a valid string which you can use to identify your products in the system configuration file.

6.3.2 Creating a Board Managed Object

To create a managed object for a board, and create a record in the OAM database for the object, enter:

oamcfg -c product [-l bus:slot] [-n brdname] [-b brdno]

where:

• product is the product string for the board type. Section 6.3.1 describes how to retrieve a list of valid product name strings.

• bus and slot describe the location of a board in the system. If this option is omitted, oamcfg assumes bus 0, slot 0.

• brdname is the name to give the board managed object. If this option is omitted, a default name is generated.

• brdno is the number to give the board (0 - 15). If this option is omitted, a default number is generated.
  Note: This operation does not require that the board currently be physically installed in the system.

If product is:

?

... oamcfg displays a list of all product types supported by the installed plug-ins, in alphabetical order.

If product is:

" "

... oamcfg chooses the first product name in this list.

For example, the following command adds a managed object for a CG 6000C board located in bus 0, slot 20:

oamcfg -c CG_6000C_QUAD -l 0:20

When a managed object is created for a board, it is assigned a unique name and board number, either of which you can use to refer to the board in future calls. To learn how to retrieve this information, see Section 6.3.4.

You can change the board name or number if you wish. For details, see Section 6.3.6.

6.3.3 Deleting a Board Managed Object

To delete a board managed object, and remove the record for the object from the OAM database, enter:

oamcfg -d [-l bus:slot] [-n brdname] [-b brdno]

where -l, -n, and/or -b identify the board to delete. If the board reference is omitted, all board managed objects are deleted.

Note: This operation does not require that the board be physically removed from the system.

For example, the following command deletes the managed object for the board named myboard:

oamcfg -d -n myboard

6.3.4 Displaying Board ID Information

When a managed object is created for a board, it is assigned a unique name and board number. You can use either the name or number to refer to the board in future calls. To display the ID parameters for a board, you can use the -q option:

oamcfg -q [-l bus:slot] [-n brdname] [-b brdno]

where -l, -n, and/or -b identify the board. If the board reference is omitted, all board ID parameters are retrieved from the database.

For example, the following command displays all ID parameters in the database:

oamcfg -q

You can change the board name or number if you wish. For details, see Section 6.3.6.

6.3.5 Changing Keyword Settings

To specify keyword settings with oamcfg, you can:

• Supply the keywords in a keyword file. oamcfg causes OAM to store the information in the OAM database.

• Specify the keywords directly on the oamcfg command line.

Specifying Settings in Keyword Files

Use the oamcfg -f option to specify a keyword file. You may include this option more than once, to specify more than one file:

oamcfg [-l bus:slot] [-n brdname] [-b brdno] -f fname [-f fname] [...]

where:

• -l, -n, and/or -b identify a board. If the component you are configuring is not a board, specify its name with the -n option.
  Note: If the component reference is omitted, oamcfg loads the keyword file for all boards.

• fname is the name of a keyword file.

For example, the following command adds the configuration information in keyword files filea.cfg and fileb.cfg to the managed object for board 0:

oamcfg -b 0 -f filea.cfg -f fileb.cfg

If you omit the path, oamcfg searches for the specified files in the current directory, and then the paths specified in the AGLOAD environment variable.

To cause oamcfg to search elsewhere, specify the entire path along with the filename on the command line.

If you specify a filename without an extension, oamcfg assumes the extension to be .cfg.

To specify whitespace within a filename, surround it with quotation marks:

oamcfg -b 0 -f "My File.cfg"

Specifying Settings on the Command Line

To set a specific keyword, you can specify it directly on the command line using the -k option:

oamcfg [-l bus:slot] [-n brdname] [-b brdno] -k keyword=value

where:

• -l, -n, and/or -b identify a board. If the component you are configuring is not a board, specify its name with the -n option.
  Note: If the component reference is omitted, oamcfg sets the keyword for all boards.

• keyword is a valid keyword name for the managed object, and value is a valid value for the keyword.

The keyword and value must be separated by an equals sign (=). For example:

oamcfg -b 0 -k DebugLevel=3

If you need to embed whitespace in a keyword/value designation, place the whole designation in quotation marks:

oamcfg -b 0 -k "DebugLevel = 3"

The -k option may appear more than once on a command line, to set multiple values. For more information about keywords and values, see Section 3.4.

6.3.6 Changing Board ID Information

You can change the name, number, or bus and slot information for a board, using the -l, -n, and -b options. To do so, specify more than one of these options on the command line, where only one of the options references information that is actually true for a board currently existing as a managed object. The rest of the options should specify new board information.

oamcfg checks the database for each option. If it determines that only one option specifies current information for an existing board, it assigns that board the name, number, or bus:slot given in the other option(s).

For example, to change the name and number of the board in bus 0, slot 20, you could specify the following (assumes that board name myboard and board number 5 do not currently exist):

oamcfg -l 0:20 -n myboard -b 5

The same board identification option cannot be specified twice on the same command line. When referencing an existing board with a given identification option, you must specify two command lines to change that option. For example, to change board number 0 to 15 (assuming that board number 15 does not currently exist), you could specify the following:

oamcfg -b 0 -n temp

oamcfg -n temp -b 15

6.3.7 Replacing Existing Data

By default, when oamcfg adds, changes, or deletes information for a managed object (using the -f or -k options), or changes board ID information (as described in Section 6.3.6), it does not disturb any other settings for the board. The -r option causes oamcfg to delete all database information for the board's managed object before adding the new information. This is useful when you want to start from a "blank slate" when changing information for a managed object:

oamcfg -b 0 -r -f filea.cfg -f fileb.cfg

6.3.8 Starting Boards

Once a board is properly configured (and is physically installed in the system), you can cause oamcfg to start the board, using the -s option:

oamcfg [-l bus:slot] [-n brdname] [-b brdno] -s

where -l, -n, and/or -b identify the board. If the board reference is omitted, oamcfg attempts to start all boards in parallel.

By default, oamcfg waits after attempting to start the boards until all board start attempts succeed or fail, reporting the results to stdout. To avoid this, you can direct oamcfg not to wait for results, using the -i option:

oamcfg -s -i

If the -i option is used, results are still available: they come asynchronously encapsulated in OAM events, which oammon can receive and display.

6.3.9 Stopping Boards

You can cause oamcfg to stop a board, using the -p option:

oamcfg [-l bus:slot] [-n brdname] [-b brdno] -p

where -l, -n, and/or -b identify the board. If the board reference is omitted, oamcfg attempts to stop all boards in parallel.

Note: The board stops immediately, interrupting any ongoing process. To avoid problems, make sure a board is not performing any operations before stopping it.

By default, oamcfg waits after attempting to stop the boards until all board stop attempts succeed or fail, reporting the results to stdout. To avoid this, you can direct oamcfg not to wait for results, using the -i option:

oamcfg -p -i

If the -i option is used, results are still available: they come asynchronously encapsulated in OAM events, which oammon can receive and display.

6.3.10 Testing Boards

You can cause oamcfg to test a board, using the -t option:

oamcfg [-l bus:slot] [-n brdname] [-b brdno] -t testopts

where -l, -n, and/or -b identify the board. If the board reference is omitted, oamcfg attempts to test all boards, in numerical order (of board numbers).

testopts is a numeric value indicating how the test will be performed. For specifics, see your board documentation.

Note: Not all board models support this operation. To learn how to test your boards, refer to your board documentation.

After attempting to start the board tests, oamcfg waits by default until all board test start attempts succeed or fail, reporting the results to stdout. To avoid this wait, you can direct oamcfg not to wait for results, using the -i option:

oamcfg -n myboard -t -i

If the -i option is used, results are still available: they come asynchronously encapsulated in OAM events, which oammon can receive and display.

6.4 Multi-Operation Invocations

You can cause a single invocation of oamcfg to perform multiple operations, by specifying more than one operation on the command line. For example, the following command line creates a managed object for a CG 6000C board in bus 0, slot 20, displays the board's ID parameters, loads keyword file cgnocc.cfg (replacing all existing information, if any) and attempts to start the board:

oamcfg -l 0:20 -c CG6000_QUAD -q -f cgnocc.cfg -r -s

6.5 Order of Operation

Regardless of the order in which the options are specified, oamcfg always performs operations in the following order:

Note: For each operation (except -c), if no specific component is referenced on the command line with the -b, -l, or -n options, the operation is performed for all board managed objects.

1. If -c is specified, creates a managed object for the board. (This is true unless -c? is specified. In this case, oamcfg displays a list of all product types supported by the installed plug-ins, in alphabetical order, and then terminates.)

2. Assigns the board a default name, number, bus, and slot. The following defaults are used:

   Item	Default
   Name	The product name, followed by a space and then a numeral. For example: CG_6000_QUAD 0
   Number	The next unused number. For example, if board 1 exists, the next number will be board 2.
   Bus	0
   Slot	0

3. Assigns board ID information, if specified on the command line. Values specified on the command line override any values previously set.
   Note: If the -r option is specified, any existing data for the board(s) is deleted when any new information is added with the -f or -k options, or if the board ID information changes (as described in Section 6.3.6).
4. In the OAM database record(s) for the managed object(s), adds the contents of any keyword file(s) specified with -f options.

5. In the OAM database record(s) for the managed object(s), sets any values specified with -k options on the command line.
   The value for a given keyword specified on the command line overrides any value for that keyword previously loaded from a keyword file.

6. If -q is specified, displays the board's name and number, or the names and numbers of all boards if no specific board is referenced on the command line.

7. If -s is specified, attempts to start the board, or all boards if no specific board is referenced on the command line.
   By default, oamcfg waits until all board start or test attempts succeed or fail, unless the -i option is specified.

8. If -p is specified, stops the board(s).

9. If -t is specified, tests the board(s).

10. If -d is specified, deletes the managed object(s) for the board(s).