3.1 Introduction

3.2 Installing the OAM Service

3.3 Initializing the OAM Service: Overview

3.4 Starting the Hot Swap Driver and Hot Swap Manager

3.4.1 Starting Hot Swap Under Windows NT

3.4.2 Starting Hot Swap Under UNIX

3.5 Starting the Natural Access Server

3.6 Initializing an NMS OAM Client Application

3.6.1 Determining Which Natural Access Mode to Use

3.6.2 Initializing the Application

Registering the OAM Service

Specifying the Natural Access Mode

Specifying a Default Natural Access Mode

3.6.3 Creating Event Queues

3.6.4 Creating CTA Contexts

3.6.5 Opening Services

3.6.6 NMS OAM Alert Notification

3.7 Automatic Startup Event Logging

3.1 Introduction

This chapter describes how to set up the Natural Access environment and start the OAM service.

3.2 Installing the OAM Service

NMS OAM is available as part of the Natural Access software package. This package is available on CD or on the NMS web site (www.nmss.com). To learn how to install the software, refer to the Natural Access CD installation booklet.

When NMS OAM is installed, the following environment variables are set or modified automatically, unless you specify otherwise:

Environment Variable	Setting/Modification
AGLOAD	\nms\oam\cfg is appended to this variable (/opt/nms/oam/cfg in UNIX)
(UNIX only) LD_LIBRARY_PATH	/opt/nms/lib:/opt/nms/hotswap/lib (Required by Hot Swap Manager)

Under Windows NT, the NMS Clock Fallback Manager service is registered.

3.3 Initializing the OAM Service: Overview

To initialize the OAM service, start the following components:

• (If your hardware supports Hot Swap) the Hot Swap driver and Hot Swap Manager. NMS OAM Hot Swap operations require that these components be running.

• The Natural Access server (ctdaemon). NMS OAM will only operate if ctdaemon is running.

To provide access to OAM service functions, a client application must:

1. Create an event queue.

2. Create a context in Server mode.

3. Open an OAM service instance on the context.

The following sections describe each of these steps. For more detailed information on each step, refer to your Natural Access Developer's Reference Manual.

3.4 Starting the Hot Swap Driver and Hot Swap Manager

The following sections describe how to start the Hot Swap driver and Manager under Windows NT and UNIX. See the NMS OAM System User's Manual for details on the Hot Swap Driver service (hssrv) and the Hot Swap Manager (hsmgr).

Note: If you stop the Hot Swap driver, reboot your system before starting it again.

3.4.1 Starting Hot Swap Under Windows NT

When Natural Access is installed, the Hot Swap driver is installed as a Windows NT driver. The Hot Swap Manager is also installed, as a Windows NT service. Both are configured to be started manually.

The Hot Swap Manager is dependent on the Hot Swap driver. Therefore, starting the Hot Swap Manager as a Windows NT service automatically starts the Hot Swap driver.

To start the Hot Swap Manager, enter:

net start hsmgr

You can set the Hot Swap Manager to start automatically using the Control Panel Services applet. To do so:

1. Open the Services applet in the Control Panel.

2. Highlight NMS Hot Swap.

3. Click the Startup... button.

4. Set the startup type to Automatic.

5. Click Close.

3.4.2 Starting Hot Swap Under UNIX

When Natural Access is installed, the Hot Swap Driver and Hot Swap Manager are placed in the /opt/nms/hotswap/bin directory. These services can be started as daemons or as console applications.

Note: The Hot Swap Manager requires the LD_LIBRARY_PATH variable to be set to LD_LIBRARY_PATH = /opt/nms/lib:/opt/nms/hotswap/lib.

To start the Hot Swap applications in console mode:

1. Start the Hot Swap Driver by entering:
   /opt/nms/hotswap/bin/hssrv

2. Start the Hot Swap Manager by entering:
   /opt/nms/hotswap/bin/hsmstart
   This script sets the LD_LIBRARY_PATH variable, and starts the Hot Swap Manager in console mode.

To start the Hot Swap applications as daemons:

1. Start the Hot Swap Driver in daemon mode by entering:
   /opt/nms/hotswap/bin/hssrv -d

2. Make sure the LD_LIBRARY_PATH variable is set as described above.

3. Start the Hot Swap Manager in daemon mode by entering:
   /opt/nms/hotswap/bin/hsmgr -d

To run the services in daemon mode at boot time (recommended), edit your /etc/inittab file to include lines which set the LD_LIBRARY_PATH variable and then start the Hot Swap Driver and Manager. In this case, do not include the
-d command-line option. For more information about the inittab file, refer to your UNIX administrator manual.

Note: The Hot Swap Driver must be started before the Hot Swap Manager.

3.5 Starting the Natural Access Server

Before you use NMS OAM or a related utility, start the Natural Access server (ctdaemon), as follows:

• (Windows NT) You can start ctdaemon in any of the following ways:

• Access a command prompt, and enter: net start ctdaemon

• In the Windows Control Panel, double-click on Services, and start the Natural Access server within this applet.

• For console interaction with the ctdaemon Windows NT service, invoke ctdaemon -c from any command prompt while the service is running.

(Windows NT or UNIX) Invoke ctdaemon -i from the command prompt. This method allows full console interaction with the ctdaemon.

Note: In order for the NMS OAM Supervisor to start up within the Natural Access server when it boots, the following line must appear in the [ctasys] section in cta.cfg (this line is included by default): Service = oam, oammgr

ctdaemon must be running for NMS OAM functions and other Server mode operations to be available. If ctdaemon is stopped, all dependent applications will receive an error. The service may need to be stopped and restarted for NMS OAM functions to become available again.

Note: Applications accessing Natural Access only in Library mode will not be affected if ctdaemon is shut down.

3.6 Initializing an NMS OAM Client Application

To access OAM service functions, a client application must:

1. Initialize Natural Access in Server or Multi mode.

2. Create event queues.

3. Create a Server mode context.

4. Open an OAM service instance on the context.

5. Register for NMS OAM alert notification (if the application needs to receive NMS OAM events).

3.6.1 Determining Which Natural Access Mode to Use

As described in Section 1.5.4, NMS OAM is designed to interact with Natural Access in its client/server configuration. Any contexts used by a Natural Access application to communicate with the OAM service must access Natural Access in this configuration.

You determine which configuration Natural Access will use, and the configuration in which contexts will be created, by specifying a mode when you initialize Natural Access with ctaInitialize (see Section 3.6.2).

The following table lists each mode, and the applications for which each mode is most appropriate:

Mode	Description
Server	Applications must use Server mode contexts to communicate with NMS OAM. When you initialize Natural Access in Server mode, you can create Server mode contexts only. Thus you should use this mode if the application · Will communicate with NMS OAM, and · Does not require the extremely efficient system resource utilization afforded by Library mode contexts.
Multi	If you initialize Natural Access in this mode, you can specify the mode (either Library or Server) for each context as you create it. Use this mode if the application · Will communicate with NMS OAM, and · Requires some Library mode contexts. This mode is most useful for legacy applications which must communicate with NMS OAM but cannot run in Server mode for some reason. In such cases, an easier solution is often to create a separate application to perform NMS OAM functions, and not to modify the legacy application.
Library	Applications can NOT use Library mode contexts to communicate with NMS OAM. Use this mode if the application · Will NOT communicate with NMS OAM, and · Requires extremely efficient system resource utilization.

3.6.2 Initializing the Application

Use ctaInitialize to initialize Natural Access applications. When you initialize Natural Access applications you

• Register the services that are available to the application

• Specify whether the application will run in Library mode, Server mode, or Multi mode, or whether the mode will be determined at runtime through settings in the cta.cfg file.

Applications must invoke ctaInitialize before calling any other Natural Access functions. For general information about ctaInitialize, refer to the Natural Access Developer's Reference Manual.

Registering the OAM Service

In the function invocation, specify the service and service manager names. Only the services initialized with ctaInitialize can be opened by an application. Service managers are dynamic link libraries (DLLs) in Windows NT and shared libraries in UNIX.

To use the OAM service, specify OAM as the service name and OAMMGR as the service manager name in the CTA_SERVICE_NAME structure passed in the ctaInitialize call.

Specifying the Natural Access Mode

Using ctaInitialize, you can also specify the default mode in which Natural Access will create contexts. If you specify Multi mode, your application can determine the mode of each context as it creates it.

Use the ctaflags field to specify the Natural Access mode for the application, as follows:

Mode	ctaflags Parameter
Library	CTA_MODE_LIBRARY
Server	CTA_MODE_SERVER
Multi	CTA_MODE_LIBRARY | CTA_MODE_SERVER

If you specify NULL as the initparms argument, the application initializes according to the information specified in the cta.cfg file (see below).

Specifying a Default Natural Access Mode

An alternative method of setting the mode is to specify it in the Natural Access configuration file (cta.cfg). If you specify the mode this way, the mode will be chosen unless it is overridden in a ctaInitialize function invocation.

To specify the mode in cta.cfg, edit the file as follows:

1. Set the CTAmode statement in the application section of the cta.cfg to any of the following:

   Mode	Corresponding cta.cfg Parameter
   Library	CTAmode=0
   Server	CTAmode=1
   Multi	CTAmode=2

2. If you select Server or Multi mode, make sure the following statements appear in the server section of cta.cfg:

   Statement	Description
   StartCtaServer=1	Enables Server mode functionality
   TraceMode=1	Enable full tracing of the server (optional but recommended)

3. Save the changes.

4. Invoke ctaInitialize and specify NULL as the initparms argument. The application initializes according to the information specified in cta.cfg.

3.6.3 Creating Event Queues

After initializing Natural Access, create one or more event queues by invoking ctaCreateQueue. Specify which service managers will be attached to each queue, to make that service manager available to the queue.

3.6.4 Creating CTA Contexts

Create a CTA context by invoking ctaCreateContext or ctaCreateContextEx (for shared contexts). You provide the queue handle (ctaqueuehd) that was returned from ctaCreateQueue. All events for services on the CTA context will be received in the specified event queue.

If Natural Access is running in Multi mode, use the descriptor string argument passed with ctaCreateContext or ctaCreateContextEx to specify the mode (Library or Server) in which the context will be created:

If descriptor is...	Then...
cta://localhost/xxx	The context is created in Server mode. (xxx can be any string.)
xxx or NULL	The context is created in Library mode. (xxx can be any string.)

ctaCreateContext and ctaCreateContextEx each return a CTA context handle (ctahd). The CTA context handle is supplied by the application when invoking service functions. Events communicated back to the application are also associated with the CTA context.

Refer to the Natural Access Developer's Reference Manual for details on the programming models created by the use of CTA contexts and event queues.

3.6.5 Opening Services

Services are opened on a CTA context by invoking ctaOpenServices. When opening a service on a CTA context, you must specify information about the service and the service manager, and which resources to attach to the CTA context. This information is specified in substructures of the CTA_SERVICE_DESC structure referenced in the function invocation.

For more information, refer to your Natural Access Developer's Reference Manual.

3.6.6 NMS OAM Alert Notification

To receive NMS OAM events, a client application must register with the Supervisor to receive alert notification messages. A client application registers for alert notification using oamAlertRegister. With this function invocation, the client application passes the handle to the OAM service. The application is immediately registered for alert notification.

To unregister from alert notifications, a client application uses oamAlertUnregister. Pass the handle to the OAM service when invoking this function. The application is immediately unregistered.

Note: Rather than unregistering, a registered client application can use ctaSetEventSources to mask out NMS OAM events. For more information, refer to the Natural Access Developer's Reference Manual.

3.7 Automatic Startup Event Logging

The following NMS OAM event logs are automatically maintained by NMS OAM:

Filename	Description
startup.log	A list of all NMS OAM events that occurred while ctdaemon was starting up. This file is rewritten whenever ctdaemon starts. It is closed after ctdaemon starts.
oam.rpt	Low-level report information generated whenever a board is started. Information on each board is appended to the file when the board is started. The file is rewritten when the server is started. Note: For users migrating from agmon: this file is the NMS OAM equivalent of the ag.rpt file output by agmon.

Both files can be found in the following locations:

• Windows NT: nms\oam\log

• UNIX: /opt/nms/oam/log