6.1 Developing AN Applications

6.2 NMS V5 Library Overview

6.3 Using the NMS V5 Library

6.3.1 Initializing the NMS V5 Library

6.3.2 Provisioning an Interface

6.3.3 Starting an NMS V5 Interface

6.3.4 Adding and Deleting E1 Links with NMS V5 Library Functions

6.3.5 Provisioning, Switching to, and Destroying a Standby Variant

6.3.6 Sending and Receiving HDLC Channel Data

6.3.7 Monitoring E1 Link Status Information

6.3.8 Controlling SA7 Bit Values on E1 Links

6.3.9 Retrieving HDLC Channel and E1 Link Status Information

6.3.10 Reprovisioning an Existing Interface

6.3.11 Stopping an Interface

6.3.12 Destroying an Interface

6.3.13 Exiting the NMS V5 Library

6.3.14 NMS V5 Library State Diagram

6.4 Aztek AV5 and NMS V5 Library Functions

6.4.1 Initializing an Interface

6.4.2 Stopping and Restarting Without Reprovisioning

6.4.3 Stopping, Reprovisioning, and Starting

6.4.4 Checking Link IDs

6.4.5 Access Network Initiated Switchover to a Variant

6.4.6 Local Exchange Initiated Switchover to a Variant

6.1 Developing AN Applications

Platform Support for DLCP provides a set of software APIs that enable applications to access on board devices (HDLC controllers and Framers) necessary to support the upper layers of a V5.2 protocol. If your AN application requires additional functionality that is beyond the scope of the Platform Support for DLCP libraries (for example, switching or voice processing), you can use other NMS products that provide this functionality.

Note: Platform Support for DLCP software is designed to work with Aztek's AV5 software, but can also be integrated with other third party V5.2 implementation software.

6.2 NMS V5 Library Overview

This section describes the operation states of the Platform Support for DLCP software. NMS V5 library software implements the Physical Layer for V.25 protocols and provides applications with a set of V5.2 protocol-specific library functions. Applications can use these functions to support the upper layers of the V5.2 interface and control HDLC and framer devices.

HDLC device controllers perform the following tasks:

• Dynamically configure, reconfigure, and destroy HDLC instances

• Initialize and reset HDLC instances

• Activate and deactivate HDLC instances

• Control the transmission and reception of HDLC frames

• Perform statistics monitoring

• Control the transmission of asynchronous events and error reports

Framer device controllers perform the following tasks:

• Monitor E1 links for alarms and errors

• Control E1 link statistic reports

• Configure SA7 bit settings for E1 links

6.3 Using the NMS V5 Library

Developers can use NMS hardware and software combined with Platform Support for DLCP NMS V5 library functions to create Access Network (AN) applications that perform the following tasks:

• Configure E1 boards.

• Configure up to three HDLC controllers per E1 link on the V5.2 interface.
  E1 link locations for HDLC links are application-configurable, but depending on the application requirements AN applications must set these links to occupy timeslots 16, 15 or 31 on two different E1 links.

• Send and receive HDLC data and error reports.

• Buffer outgoing and incoming messages for each HDLC channel.

• E1 framers detect and report the following:

• Loss-of-Frame and Loss-of-Signal reports.

• Sending and receiving alarm indicator signals (AIS) and remote alarm indications (RAIs).

• Set, reset, or read operations associated with the SA7 framing bit

• Monitor Far End Block Error (FEBE) counters.

Supports the lower level switching fabric required by the V5.2 protocol.

Perform NMS V5 library tracing.

NMS V5 library functions allow applications to perform the following tasks:

• Initializing the software.

• Provisioning interfaces (for active and standby variants).

• Starting and stopping interfaces.

• Switching to and from standby variants.

• Adding and deleting E1 links

• Monitoring E1 links through link status and statistics queries.

• Performing HDLC transmit and receive operations such as sending and receiving LAPV frames on HDLC channels.

6.3.1 Initializing the NMS V5 Library

When the AN system starts up, the application should invoke NMS_V5Initialize. to load the NMS V5 library, start the library's internal processing tasks, and initialize its internal software structures.

The application can invoke NMS_V5SetTrace any time after the loading the NMS V5 library. Arguments for NMS_V5SetTrace specify the level of tracing performed by the library, and whether the library returns tracing information to the application or logs the information in a file.

6.3.2 Provisioning an Interface

Before data can flow through HDLC channels and the NMS V5 library can return E1 status reports, applications must start V5.2 interfaces. After the application initializes the V5.2 physical layer software (the NMS V5 library), it must call
NMS_V5ProvisionInterface to provision V5.2 interfaces. When invoking NMS_V5ProvisionInterface, applications provide hardware-specific HDLC channel and E1 link location information, define callback functions for processing HDLC data and E1 reports, and allocate memory for receiving data from the physical layer. The NMS V5 library configures and resets the HDLC channels on the board, starts monitoring the provisioned E1 links, and resets its internal statistics structures. By default, the SA7 framing bit is set to 1 for newly provisioned E1 links.

The NMS V5 library begins to monitor E1 links after the application has provisioned interfaces. Applications can invoke NMS_V5GetE1Status and NMS_V5ResetE1Status to obtain or reset the E1 link status information from the boards.

Note: NMS recommends that applications provision and start the upper layers of the V5.2 protocol stack after they start the physical layer with NMS_V5StartInterface. In some cases, the provisioned interfaces can expect incoming HDLC traffic after they are provisioned but before they are started.

Applications must establish a mapping between the physical layer HDLC channel and E1 link locations (which are NMS hardware-specific) and the upper layer V5.2 protocol structures. The Physical layer does not track protocol information for the hardware resource assignments (for example, whether an E1 link is in active or standby mode, or what C-channel assignments apply to a particular timeslot). This information is out of scope of the physical layer and should be controlled by the upper layers of the V5.2 protocol software and by the application.

6.3.3 Starting an NMS V5 Interface

To start NMS V5 interfaces, applications call NMS_V5StartInterface for each interface they want to start. After the application starts an interface, the HDLC channels provisioned on the interface become operational and data begins to flow across the E1 links. In addition, the NMS V5 library begins to report E1 alarms and remote SA7 framing bit value changes to the application.

If the local exchange is connected and active on the other side of the interface, the application can expect to receive LAPV messages though the E1 connections.

After the interface is started, the application can invoke the following functions:

Function	Description
NMS_V5PhSendData	Passes data received from the upper layers of the V5.2 stack to the physical layer. The physical layer then sends the data to the appropriate HDLC channel.
NMS_V5GetE1Status	Retrieve information about an E1 link.
NMS_V5ResetE1Status	Reset the status of an E1 link.
NMS_V5GetChannelStatistics	Access HDLC channel statistics.
NMS_V5ResetChannelStatistics	Reset HDLC channel statistics.
NMS_V5AddE1	Add an E1 link (associated with voice channels) to a provisioned active variant on a specified interface.
NMS_V5DeleteE1	Delete an E1 link from an active variant of a provisioned interface.

6.3.4 Adding and Deleting E1 Links with NMS V5 Library Functions

To add or delete E1 links carrying HDLC channels, the application must first stop and re-provision the interface. However, applications can add or delete E1 links associated with voice data (rather than HDLC data) without stopping and re-provisioning the active variant of a provisioned interface by calling NMS_V5AddE1 or NMS_V5DeleteE1. If the application invokes NMS_V5AddE1 for a started interface, the NMS V5 library automatically begins to monitor the new E1 link.

6.3.5 Provisioning, Switching to, and Destroying a Standby Variant

Applications can invoke NMS_V5ProvisionStandByVariant to configure a standby variant for any provisioned interface. HDLC channel and E1 link locations on standby variants can overlap with channel and link locations configured for active variants. The NMS V5 library saves the standby variant configuration but does not validate it.

To switch from the active NMS V5 interface to a standby variant, the application can invoke NMS_V5SwitchOverVariantData. NMS_V5SwitchOverVariantData stops the active variant, destroys any associated provision information, and activates the provision for the standby variant. If the re-provisioning is successful, the standby variant becomes the provisioned active variant of the interface. However, the application must still call NMS_V5StartInterface to start the interface.

Note: Applications should call NMS_V5SwitchOverVariantData after the upper level of the V5.2 (in this case, the AV5 stack) interface has finishes its switchover process.

To add or delete E1 links on a standby variant of an interface, the application must first destroy the standby variant with NMS_V5DestroyStandByVariant and then re-provision the variant with NMS_V5ProvisionStandByVariant. If the call to NMS_V5SwitchOverVariantData fails, both the active and the failed standby variants of the existing interface are destroyed. The application must then invoke NMS_V5DestroyInterface and NMS_V5ProvisionInterface to re-provision the interface.

6.3.6 Sending and Receiving HDLC Channel Data

Applications can use NMS_V5PhSendData to asynchronously send data to HDLC channels on a started interface.

When the NMS V5 library finishes sending the data, it returns the results of the operation to the application. If necessary, the NMS V5 library performs internal buffering for outgoing messages associated with each HDLC data channel. If the outgoing message queue overflows, the NMS V5 library uses an application-defined callback function to return a notification error. The NMS V5 library uses a callback function to pass the incoming HDLC messages up to the application. The HDLC data is copied into memory that was allocated by the application when it provisioned the interface.

6.3.7 Monitoring E1 Link Status Information

When the interface is provisioned, the NMS V5 library starts monitoring E1 links for alarms and remote SA7 framing bit changes. After the application starts an interface, the library invokes the application-defined callback function to report alarm events (LOS, LOF, AIS, RAI, normal frames, SA7 framing bit value updates). The first report on the current E1 state is sent to the application immediately when it starts. After that, the NMS V5 library only sends status when the E1 links change their state.

The application can use NMS_V5GetE1Status to query the NMS V5 library for E1 link state information any time after the interface has been provisioned. When the interface is destroyed, the NMS V5 library stops monitoring any E1 links associated with the interface. The application can also use NMS_V5ResetE1Status to reset the status information associated with an E1 link.

6.3.8 Controlling SA7 Bit Values on E1 Links

According to the link ID check procedure defined by the V5.2 protocol, the V5.2 protocol stack must be able to control the SA7 E1 framing bit. When an application provisions an interface, destroys an interface, or exits the NMS V5 library, the library automatically sets the SA7 bit to 1 on any associated E1 links. The NMS_V5SendSA7Bit function enables applications to set the SA7 bit value to 0 or 1 for a specified E1 link.

6.3.9 Retrieving HDLC Channel and E1 Link Status Information

When an application provisions an interface, the board automatically starts to monitor any provisioned E1 links. When the application starts the interface, the NMS V5 library begins to collect statistics for provisioned HDLC channels. Applications can invoke NMS_V5GetE1Status to query E1 status information or invoke NMS_V5GetChannelStatistics to retrieve HDLC channel statistics for a particular HDLC channel.

NMS_V5GetE1Status returns current E1 link status and error history information (collected over an elapsed period of time). NMS_V5GetChannelStatistics reports success and error history information for both receive and transmit directions on a specified HDLC channel.

To reset the HDLC channel statistics or E1 link status the application can call NMS_V5ResetChannelStatistics or NMS_V5ResetE1Status.

6.3.10 Reprovisioning an Existing Interface

To reprovision an existing interface with NMS V5 library functions, the application must perform the following steps:

1. Stop the interface (if the interface is started) with NMS_V5StopInterface.

2. Destroy the current interface with NMS_V5DestroyInterface. This function destroys both the active and standby variants of the interface. Destroyed E1 links will have SA7 framing bit set to 1.

3. Reprovision the interface by invoking NMS_V5ProvisionInterface. Provisioned E1 links will have SA7 framing bit set to 1.

4. Start the new interface with NMS_V5StartInterface.

6.3.11 Stopping an Interface

Applications invoke NMS_V5StopInterface to stop an existing interface. When the application stops an interface, the interface remains provisioned but not operational. The flow of HDLC data through the interface stops and the NMS V5 library no longer returns E1 link alarm reports. However, the NMS V5 library continues to monitor E1 links and to maintain channel statistics.

Applications can still query E1 link status information and reset the status of E1 links associated with stopped interfaces. In addition, the NMS V5 library does not automatically reset HDLC channel statistics when the application stops an interface. The application can retrieve HDLC channel statistics or to reset these statistics.

To restart a stopped interface, AV applications can invoke NMS_V5StartInterface.

6.3.12 Destroying an Interface

Applications must invoke NMS_V5DestroyInterface to destroy an interface. When the interface is destroyed, the flow of HDLC data stops, and the NMS V5 library stops monitoring E1 link links associated with the interface. The NMS V5 library destroys any provision information for the active and standby variants of the interface. Destroyed E1 links will have SA7 framing bit set to 1.

To destroy only the standby variant of an existing interface, applications can invoke NMS_V5DestroyStandByVariant.

6.3.13 Exiting the NMS V5 Library

To exit gracefully the AN system the applications call NMS_V5Exit. When the application calls NMS_V5Exit, the NMS V5 library stops all provisioned HDLC channels, disables E1 link monitoring, resets the SA7 framing bit to 1 on all E1 links, and destroys all provisioned interfaces. Exiting the AN application gracefully (that is, invoking NMS_V5StopInterface and NMS_V5DestroyInterface before invoking NMS_V5Exit) brings the boards to a known state, and allows you to restart the application without rebooting the boards.

6.3.14 NMS V5 Library State Diagram

Figure 12 shows a state diagram for interfaces controlled through the NMS V5 library. Developers must comply with the illustrated conditions when integrating NMS V5 library functions into AN applications.

Figure 12. NMS V5 Interface State Transitions

The following table describes the NMS V5 library interface states:

State	Description
Null	The board is booted and initialized with the user configuration, but the NMS V5 physical library is not loaded.
Idle	The NMS V5 library is initialized. No communication link is established between the application and the boards. Library tracing can be configured.
Provisioned	The interface is provisioned on the physical layer. All necessary connections are made between the application and HDLC/Framer instances on the boards. HDLC channels are configured, reset, and initialized, but disabled for receive and transmit operations. By default, the SA7 framing bit is set to 1 for provisioned E1 links. The application can query status of HDLC channels and DS1 links, modify provisioned configurations, and configure library tracing.
Started	The HDLC channels are enabled for transmit and receive operations. Applications can provision or destroy a standby variant, add or delete E1 links to an active interface variant, toggle the SA7 bit for provisioned E1 links, and query HDLC channel and E1 link status. Applications can also switch the interface to a standby variant, and configure library tracing.

6.4 Aztek AV5 and NMS V5 Library Functions

The following diagrams illustrate scenarios for combining Aztek AV5 library and NMS V5 library function calls to perform interface management and LAPV data communication over E1 links. For more information about Aztek AV5 library functions, refer to the Aztek documentation.

6.4.1 Initializing an Interface

The following diagram shows functions used to initialize a V5.2 interface:

Figure 13. Initializing a V5.2 Interface

6.4.2 Stopping and Restarting Without Reprovisioning

The following diagram shows functions used to the stop and restart an V5.2 interface without reprovisioning:

Figure 14. Stopping and Starting a V5.2 Interface without Provisioning

6.4.3 Stopping, Reprovisioning, and Starting

The following diagram shows functions used to stop, reprovision, and start a V5.2 interface:

Figure 15. Stopping, Reprovisioning, and Starting a V5.2 Interface

6.4.4 Checking Link IDs

The following diagram shows functions used to check V5.2 link IDs:

Figure 16. Checking Link IDs

6.4.5 Access Network Initiated Switchover to a Variant

The following diagram shows functions used to provision a V5.2 variant interface, and then to perform an Access Network initiated switchover operation:

Figure 17. Access Network Initiated Switch to a Variant V5.2 Interface

6.4.6 Local Exchange Initiated Switchover to a Variant

The following diagram shows functions used to provision a V5.2 variant interface, and then to perform an Local Exchange initiated switchover operation:

Figure 18. Local Exchange Initiated Switch to a Variant V5.2 Interface