Introduction

Summary of Changes

agmon vs. OAM

OAM Service Utilities

Configuration Files

ag2oam

Board Identification

Hot Swap Changes

Introduction

This appendix discusses migration from agmon to OAM.

Summary of Changes

OAM was introduced with CT Access 4.0. This section summarizes the changes incurred with the introduction of OAM:

• The AG board configuration and monitoring utility, agmon, is deprecated. OAM now performs board management operations across all boards, including AG, QX, CX and CG models. Utilities included with OAM duplicate and enhance operations formerly performed by agmon.

• The AGM library is deprecated. OAM has a full-featured API for initializing and monitoring boards, and for performing many other tasks.

• The AG configuration file has been replaced by files with very different structure and syntax. Keywords used in these files are very different from AG configuration file keywords.
  The ag2oam utility included with OAM translates AG configuration files into the new syntax.

• Previously, the only method of identifying a board in software was the board number. A new identifier, the name, can now also be used to identify each board, as well as certain software modules and other components.

• The HSI service is deprecated. Hot Swap functionality is implemented as an extended component of OAM. Note that the Hot Swap Manager has not changed.

• The QX board configuration and monitoring utility, qxload, is deprecated. OAM now performs board management operations for QX boards. For information about migrating QX applications to OAM, refer to the QX 2000 Installation and Developer's Manual.

• NMS SNMP services now use OAM services. Therefore, SNMP can only provide information on boards started using the OAM service.

agmon vs. OAM

agmon is deprecated as of Natural Access 2000-1. A new CT Access service, OAM, provides all functionality formerly provided by agmon. OAM differs from agmon in the following major ways:

• agmon is a utility program, controllable only using its command line. OAM is a bona fide CT Access service, accessible programmatically using its extensive API. Various subsets of OAM service functionality can also be accessed with the oamsys, oamcfg, and oammon utilities.

• agmon configures, boots, and then monitors boards, as a single operation. With OAM, configuration, board starting/stopping, and monitoring operations are all accessible separately, using the OAM utilities and API functions.

• With agmon, the central repository of configuration information is the AG configuration file. With OAM, configuration information is kept in a dynamic database, managed by the service. The configuration information for a given board is called the managed object for the board.
  The utilities supplied with OAM use configuration files as a convenient way to supply information to the OAM database. However, when OAM starts (boots) boards, the information in the managed object for each board (not the configuration files) determines how the board will be configured.

• OAM provides functionality not available with agmon, such as board testing (for board models that support this operation) and alert notification. It is also extensible with extended management components (EMCs) and board plug-ins. For example, Hot Swap is now implemented as an EMC.

• OAM supports new board families, such as CG.

• OAM and agmon cannot be used simultaneously.

OAM Service Utilities

The following utilities are supplied with OAM:

Utility	Description
oamsys	Mimics agmon's configuration and booting capabilities: configures the OAM database based on information supplied in configuration files, and then causes OAM to start all boards.
oamcfg	Provides access to individual OAM configuration functions. Can also read configuration files, to configure individual boards.
oammon	Mimics agmon's monitoring capabilities: it monitors boards for board-level errors and events.
oaminfo	Allows you to display and set OAM keywords. Can also search for text in keywords. For more information about oaminfo, refer to the OAM Service Developer's Reference Manual.

Configuration Files

With agmon, all information for all boards was specified in a single AG configuration file. With OAM utilities, a system configuration file contains a list of managed components in the system (boards or software modules, such as an EMC). For each managed component, a list is specified of parameters and values to configure that component. (Most of the parameters for boards are usually listed in separate keyword files referenced in the system configuration file.)

The syntax of these files is very different from the syntax of an AG configuration file. Parameters are still specified as keyword name/value pairs (for example, AutoStart = YES). However, struct keywords (containing multiple values) and array keywords (containing multiple indexed values) are now supported. These keywords are often specified using a special shorthand notation.

Keyword names have been made as consistent as possible across board families.

For more information about system configuration files, see Chapter 3. For more information about keyword files, see Section 3.4. For more information about OAM equivalents for specific AG configuration file keywords, refer to your board documentation.

ag2oam

Included with the OAM software is a utility, ag2oam, which translates AG configuration files into system configuration files and keyword files which oamsys can process. To use ag2oam:

1. Go through the AG configuration file, and determine the product type for each board number. For example, Board 0 = AG Quad T1; Board 1 = AG Quad T1; Board 2 = AG 4000C T1.

2. Enter: ag2oam [options]
   where options are:

   Option	Description
   -c	Causes ag2oam to duplicate in the output files any comments it finds in the original file. If this option is not specified, comment lines are omitted.
   -f filename	Name (and path, if necessary) of AG configuration file to translate. Default is ag.cfg. If no path is specified, ag2oam searches first in the current directory, and then in the paths specified with the AGLOAD environment variable.
   -p[m[..n]=] product	AG product type for board(s) m...n. This option can appear on the command line as many times as necessary. If you do not specify board numbers, the specified product types used for all boards. Section 6.3.1 describes how to get a list of valid values for product. Note: ISA boards are not supported, since they are not supported by OAM.
   -?	Causes ag2oam to display its help screen, and terminate.
   -h	Causes ag2oam to display its help screen, and terminate.

For example, with the configuration listed in step 1 above, you would enter:

ag2oam -f myfile.cfg -p0..1=AG_Quad_T1 -p2=AG_4000C_T1

If the operation is successful, ag2oam returns without a message. ag2oam outputs the following files, in the same path as the source file:

• A system configuration file, listing all boards from your AG configuration file. This file is named oldname_oamsys.cfg, where oldname is the name of your AG configuration file, minus the extension. For example: myfile_oamsys.cfg

• One or more keyword files, one for each board listed in your AG configuration file. This file is named oldname_Board_n.cfg, where oldname is the name of your AG configuration file, minus the extension, and n is the number of the board as it appeared in your AG configuration file. For example: myfile_Board_0.cfg
  The keyword file for each board is appropriately referenced in the system configuration file, in the section describing the board.
  Note: ag2oam assumes that the input AG configuration file is valid. If errors exist in the input file, in most cases they will be propagated in the output files.

Board Identification

Previously, the board number was the only way of identifying a board in software. This number was assigned in the AG configuration file. With the OAM service, boards are also identified by board names. The board name for a board is assigned when the managed object is first created in the OAM database for the board. You can specify the name of a board in the system configuration file you supply to oamsys (see Chapter 3).

Names are also used for other types of managed objects, such as extended management components (EMCs), board plug-ins, and the OAM Supervisor itself. For details, see Chapter 1.

Most NMS API software still requires board numbers. Within OAM, boards are still assigned unique board numbers, and you can still use this method to identify them in software. Within the OAM service, you can also identify a board using its location (bus and slot), as well as with other information. For details, see Section 1.4.2.

Hot Swap Changes

Previously, the Hot Swap interface to CT Access was implemented as a CT Access service (the HSI service). This interface is now implemented as an OAM extended management component (EMC). Changes to the API made as a result of the OAM implementation are listed below. For details, refer to the OAM Service Developer's Reference Manual.

• The HSI service is now deprecated, and is not compatible with OAM.

• The information formerly returned by HSI functions hsiGetBoardInfo and hsiGetLogicalBoardInfo is now available using other means, as follows:

  Information	New Source
  Board information	oamBoardGetXXX and oamBoardLookupByXXX functions
  Hot Swap state	Board.name.State keyword in the Hot Swap EMC managed object

• Hot Swap events are now passed to applications using the same event handling mechanism used for OAM events. Hot Swap events and errors have not changed, except for their prefixes: Hot Swap events now have the prefix HSWEVN_, and Hot Swap error codes now have the prefix HSWERR_. They are specified in hswdef.h.

• Hot Swap state names have changed, to be closer to their SNMP equivalents:

  Old State Name	New State Name
  NOT PRESENT	Extracted
  OFFLINE	OffLine
  PREPARATION	OnLinePending
  PREPARATION FAILED	Failed
  RUNNING	OnLine
  DOWNING	OffLinePending
  (none -- see below)	Unsupported

• A new state has been added to the state machine: Unsupported. If a board does not support Hot Swap, it is permanently in this state.

• The Hot Swap Developer's Manual is now obsolete. Hot Swap runtime information is documented in the manual you are currently reading. Hot Swap developer information is in the OAM Service Developer's Reference Manual.