<!doctype HTML public "-//W3C//DTD HTML 4.0 Frameset//EN">

<html>

<head>
<title>NaturalAccess GR303 and V5 Libraries Developer's Manual: Using the NMS V5 library </title>
<meta http-equiv="content-type" content="text/html; charset=windows-1252">
<meta name=NMSConversion content="4.0.8">
<meta name="generator" content="RoboHelp by eHelp Corporation www.ehelp.com">
<link rel="stylesheet" href="dialogic_ns.css"><script type="text/javascript" language="JavaScript" title="WebHelpSplitCss">
<!--
if (navigator.appName !="Netscape")
{   document.write("<link rel='stylesheet' href='dialogic.css'>");}
//-->
</script>
<style type="text/css">
<!--
ul.whs1 { list-style:disc; }
table.whs2 {   x-border-left:1px table-solid; x-border-top:1px table-solid; x-border-right:1px table-solid; x-border-bottom:1px table-solid; border-collapse:separate; border-spacing:0px; }
tr.whs3 { background-color:#CCCCCC; x-cell-content-align:top; vertical-align:top; }
td.whs4 { vertical-align:top; padding-left:5px;  padding-right:5px;  }
p.whs5 { font-weight:bold; }
tr.whs6 { x-cell-content-align:top; vertical-align:top; }
table.whs7 { width:100%;   x-border-left:1px table-solid; x-border-top:1px table-solid; x-border-right:1px table-solid; x-border-bottom:1px table-solid; border-collapse:separate; border-spacing:0px; }
col.whs8 { width:7.152%; }
col.whs9 { width:92.848%; }
td.whs10 { width:7.152%; background-color:#CCCCCC; vertical-align:top;   padding-right:10px; padding-left:10px; }
td.whs11 { width:92.848%; background-color:#CCCCCC; vertical-align:top;   padding-right:10px; padding-left:10px; }
td.whs12 { width:7.152%; background-color:#ffffff; vertical-align:top;   padding-right:10px; padding-left:10px; }
td.whs13 { width:92.848%; background-color:#ffffff; vertical-align:top;   padding-right:10px; padding-left:10px; }
img_whs14 { float:none; width:484px; height:565px; border-style:none; }
div.whs15 { width:100%; }
p.whs16 { text-align:center; }
p.whs17 { text-align:center; font-size:xx-small; }
-->
</style><script type="text/javascript" language="JavaScript">
<!--
if ((navigator.appName == "Netscape") && (parseInt(navigator.appVersion) == 4))
{
  var strNSS = "<style type='text/css'>";
  strNSS += "p.whs17 {font-size:x-small; }";
  strNSS +="</style>";
  document.write(strNSS);
}
//-->
</script>
<script type="text/javascript" language="JavaScript" title="WebHelpInlineScript">
<!--
function reDo() {
  if (innerWidth != origWidth || innerHeight != origHeight)
     location.reload();
}
if ((parseInt(navigator.appVersion) == 4) && (navigator.appName == "Netscape")) {
	origWidth = innerWidth;
	origHeight = innerHeight;
	onresize = reDo;
}
onerror = null; 
//-->
</script>
<style type="text/css">
<!--
div.WebHelpPopupMenu { position:absolute; left:0px; top:0px; z-index:4; visibility:hidden; }
-->
</style><script type="text/javascript" language="javascript1.2" src="whmsg.js"></script>
<script type="text/javascript" language="javascript" src="whver.js"></script>
<script type="text/javascript" language="javascript1.2" src="whproxy.js"></script>
<script type="text/javascript" language="javascript1.2" src="whutils.js"></script>
<script type="text/javascript" language="javascript1.2" src="whtopic.js"></script>
</head>
<body><script type="text/javascript" language="javascript1.2">
<!--
if (window.gbWhTopic)
{
	if (window.addTocInfo)
	{
	addTocInfo("NMS V5 programming model\nUsing the NMS V5 library");
addAvenueInfo("Untitled","developing_an_applications_.htm","programming_scenarios_(v5.htm");
addButton("show",BTN_TEXT,"Show table of contents for this manual","","","","",0,0,"","","");

	}
	if (window.writeBtnStyle)
		writeBtnStyle();

	if (window.writeIntopicBar)
		writeIntopicBar(1);

	if (window.setRelStartPage)
	{
	setRelStartPage("default.htm");

		autoSync(1);
		sendSyncInfo();
		sendAveInfoOut();
	}
}
else
	if (window.gbIE4)
		document.location.reload();
//-->
</script>
<h1>Using the 
 NMS V5 library</h1>

<p>This topic presents the following information:</p>

<ul type="disc" class="whs1">
	
	<li class=kadov-p><p><a href="#Initializing the NMS V5 library">Initializing 
 the NMS V5 library</a></p></li>
	
	<li class=kadov-p><p><a href="#Provisioning_an_NMS_V5_interface">Provisioning 
 an NMS V5 interface</a></p></li>
	
	<li class=kadov-p><p><a href="#Starting an NMS V5 interface">Starting 
 an NMS V5 interface</a></p></li>
	
	<li class=kadov-p><p><a href="#Adding_and_deleting_E1_links">Adding 
 and deleting E1 links</a></p></li>
	
	<li class=kadov-p><p><a href="#Adding_and_deleting_HDLC_channels">Adding 
 and deleting HDLC channels</a></p></li>
	
	<li class=kadov-p><p><a href="#Provisioning, switching to, and destroying a stand">Provisioning, 
 switching to, and destroying a standby variant</a></p></li>
	
	<li class=kadov-p><p><a href="#Sending and receiving HDLC channel data">Sending 
 and receiving HDLC channel data</a></p></li>
	
	<li class=kadov-p><p><a href="#Monitoring E1 link status information">Monitoring 
 E1 link status information</a></p></li>
	
	<li class=kadov-p><p><a href="#Controlling SA7 bit values on E1 links">Controlling 
 SA7 bit values on E1 links</a></p></li>
	
	<li class=kadov-p><p><a href="#Retrieving HDLC channel and E1 link status informa">Retrieving 
 HDLC channel and E1 link status information</a></p></li>
	
	<li class=kadov-p><p><a href="#Reprovisioning an existing interface">Re-provisioning 
 an existing interface</a></p></li>
	
	<li class=kadov-p><p><a href="#Stopping an interface">Stopping an interface</a></p></li>
	
	<li class=kadov-p><p><a href="#Destroying an interface">Destroying 
 an interface</a></p></li>
	
	<li class=kadov-p><p><a href="#Exiting the NMS V5 library">Exiting 
 the NMS V5 library</a></p></li>
	
	<li class=kadov-p><p><a href="#NMS V5 library state diagram">NMS V5 
 library state model</a></p></li>
</ul>

<h2><a name="Initializing the NMS V5 library"></a>Initializing the NMS 
 V5 library</h2>

<p>When the AN system starts up, invoke <a href="nmsv5initialize.html"><span 
 style="color: #0000ff;
		font-style: normal;
		font-weight: bold;
		x-text-underline: off;
		x-text-overline: off;
		x-text-line-through: off;
		text-transform: none;
		vertical-align: baseline;
		/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5Initialize</B></font></span></a>. 
 to load the NMS V5 library, start the library's internal processing tasks, 
 and initialize its internal software structures.</p>

<p>Invoke <a href="nmsv5settrace.html"><span style="color: #0000ff;
													font-weight: bold;
													x-text-underline: off;
													/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5SetTrace</B></font></span></a> 
 any time after loading the NMS V5 library. Arguments for <span style="font-weight: bold;"><B>NMS_V5SetTrace</B></span> 
 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.</p>

<h2><a name=Provisioning_an_NMS_V5_interface></a>Provisioning an NMS V5 
 interface</h2>

<p>Before data can flow through HDLC channels and the NMS V5 library can 
 return E1 status reports, applications must start V5.2 interfaces. After 
 initializing the V5.2 physical layer software (the NMS V5 library), call 
 <a href="nmsv5provisioninterface.html"><span style="color: #0000ff;
														font-weight: bold;
														x-text-underline: off;
														/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5ProvisionInterface</B></font></span></a> 
 to provision V5.2 interfaces. When invoking <span style="font-weight: bold;"><B>NMS_V5ProvisionInterface:</B></span></p>

<ul type="disc" class="whs1">
	
	<li class=kadov-p><p>Provide hardware-specific HDLC channel and E1 
 link location information.</p></li>
	
	<li class=kadov-p><p>Define callback functions for processing HDLC 
 data and E1 reports.</p></li>
	
	<li class=kadov-p><p>Allocate memory for receiving data from the physical 
 layer.</p></li>
</ul>

<p>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. </p>

<p>The NMS V5 library begins to monitor E1 links after the application 
 provisions the interfaces. Applications can then invoke <a href="nmsv5gete1status.html"><span 
 style="color: #0000ff;
		font-style: normal;
		font-weight: bold;
		x-text-underline: off;
		x-text-overline: off;
		x-text-line-through: off;
		text-transform: none;
		vertical-align: baseline;
		/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5GetE1Status</B></font></span></a> 
 and <a href="nmsv5resete1status.html"><span style="color: #0000ff;
													font-style: normal;
													font-weight: bold;
													x-text-underline: off;
													x-text-overline: off;
													x-text-line-through: off;
													text-transform: none;
													vertical-align: baseline;
													/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5ResetE1Status</B></font></span></a> 
 to obtain or reset E1 link status information for the E1 links.</p>

<p class=Note><span style="font-weight: bold;"><B>Note: </B></span>NMS recommends 
 that applications provision and start the upper layers of the V5.2 protocol 
 stack after they start the physical layer with <a href="nmsv5startinterface.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5StartInterface</B></font></span></a>. 
 In some cases, the provisioned interfaces can expect incoming HDLC traffic 
 before the application starts them.</p>

<p>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.</p>

<h2><a name="Starting an NMS V5 interface"></a>Starting an NMS V5 interface</h2>

<p>To start NMS V5 interfaces, call <a href="nmsv5startinterface.html"><span 
 style="color: #0000ff;
		font-style: normal;
		font-weight: bold;
		x-text-underline: off;
		x-text-overline: off;
		x-text-line-through: off;
		text-transform: none;
		vertical-align: baseline;
		/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5StartInterface</B></font></span></a> 
 for each interface you 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. </p>

<p>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. </p>

<p>After starting the interface, you can invoke the following functions: 
 </p>

<table cellpadding="5" x-use-null-cells cellspacing="0" border="1" class="whs2">

<tr bgcolor="#CCCCCC" valign="top" class="whs3">
<td class="whs4">
<p class="whs5">Function</p></td>
<td class="whs4">
<p class="whs5">Description</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p><a href="nmsv5phsenddata.html"><span style="color: #0000ff;
												font-style: normal;
												font-weight: bold;
												x-text-underline: off;
												x-text-overline: off;
												x-text-line-through: off;
												text-transform: none;
												vertical-align: baseline;
												/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5PhSendData</B></font></span></a></p></td>
<td class="whs4">
<p>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.</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p><a href="nmsv5gete1status.html"><span style="color: #0000ff;
												font-style: normal;
												font-weight: bold;
												x-text-underline: off;
												x-text-overline: off;
												x-text-line-through: off;
												text-transform: none;
												vertical-align: baseline;
												/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5GetE1Status</B></font></span></a></p></td>
<td class="whs4">
<p>Retrieves information about an E1 link.</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p><a href="nmsv5resete1status.html"><span style="color: #0000ff;
													font-style: normal;
													font-weight: bold;
													x-text-underline: off;
													x-text-overline: off;
													x-text-line-through: off;
													text-transform: none;
													vertical-align: baseline;
													/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5ResetE1Status</B></font></span></a></p></td>
<td class="whs4">
<p>Resets the status of an E1 link.</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p><a href="nmsv5getchannelstatistics.html"><span style="color: #0000ff;
															font-style: normal;
															font-weight: bold;
															x-text-underline: off;
															x-text-overline: off;
															x-text-line-through: off;
															text-transform: none;
															vertical-align: baseline;
															/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5GetChannelStatistics</B></font></span></a></p></td>
<td class="whs4">
<p>Accesses HDLC channel statistics.</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p><a href="nmsv5resetchannelstatistics.html"><span style="color: #0000ff;
															font-style: normal;
															font-weight: bold;
															x-text-underline: off;
															x-text-overline: off;
															x-text-line-through: off;
															text-transform: none;
															vertical-align: baseline;
															/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5ResetChannelStatistics</B></font></span></a></p></td>
<td class="whs4">
<p>Resets HDLC channel statistics.</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p><a href="nmsv5adde1.html"><span style="color: #0000ff;
											font-style: normal;
											font-weight: bold;
											x-text-underline: off;
											x-text-overline: off;
											x-text-line-through: off;
											text-transform: none;
											vertical-align: baseline;
											/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5AddE1</B></font></span></a></p></td>
<td class="whs4">
<p>Adds an E1 link (associated with voice channels) to a provisioned active 
 variant on a specified interface.</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p><a href="nmsv5deletee1.html"><span style="color: #0000ff;
												font-style: normal;
												font-weight: bold;
												x-text-underline: off;
												x-text-overline: off;
												x-text-line-through: off;
												text-transform: none;
												vertical-align: baseline;
												/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DeleteE1</B></font></span></a></p></td>
<td class="whs4">
<p>Deletes an E1 link from an active variant of a provisioned interface.</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p><a href="nmsv5addchannel.html"><span style="color: #0000ff;
												font-style: normal;
												font-weight: bold;
												x-text-underline: off;
												x-text-overline: off;
												x-text-line-through: off;
												text-transform: none;
												vertical-align: baseline;
												/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5AddChannel</B></font></span></a></p></td>
<td class="whs4">
<p>Adds an HDLC channel (usually associated with an ISDN data channel) 
 to a provisioned active variant on a specified interface.</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p><a href="nmsv5deletechannel.html"><span style="color: #0000ff;
													font-style: normal;
													font-weight: bold;
													x-text-underline: off;
													x-text-overline: off;
													x-text-line-through: off;
													text-transform: none;
													vertical-align: baseline;
													/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DeleteChannel</B></font></span></a></p></td>
<td class="whs4">
<p>Removes an HDLC channel from a provisioned active variant on a specified 
 interface.</p></td></tr>
</table><br>

<h2><a name=Adding_and_deleting_E1_links></a>Adding and deleting E1 links</h2>

<p>Applications can add or delete E1 links associated with voice and HDLC 
 data without stopping and re-provisioning the active variant of a provisioned 
 interface by calling <a href="nmsv5adde1.html"><span style="color: #0000ff;
	font-weight: bold;
	x-text-underline: off;
	/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5AddE1</B></font></span></a> 
 or <a href="nmsv5deletee1.html"><span style="color: #0000ff;
												font-weight: bold;
												x-text-underline: off;
												/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DeleteE1</B></font></span></a>. 
 If the application invokes <span style="font-weight: bold;"><B>NMS_V5AddE1</B></span> 
 for a started interface, the NMS V5 library automatically begins to monitor 
 the new E1 link.</p>

<p>Later the application can add HDLC channels to an existing E1 link by 
 calling <a href="nmsv5addchannel.html"><span style="color: #0000ff;
														font-style: normal;
														font-weight: bold;
														x-text-underline: off;
														x-text-overline: off;
														x-text-line-through: off;
														text-transform: none;
														vertical-align: baseline;
														/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5AddChannel</B></font></span></a>, 
 or delete an HDLC channel from an existing (or already deleted E1 link) 
 by calling <a href="nmsv5deletechannel.html"><span style="color: #0000ff;
															font-style: normal;
															font-weight: bold;
															x-text-underline: off;
															x-text-overline: off;
															x-text-line-through: off;
															text-transform: none;
															vertical-align: baseline;
															/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DeleteChannel</B></font></span></a>. 
 The application cannot remove a provisioned E1 link if this link still 
 has HDLC channels provisioned on it.</p>

<h2><a name=Adding_and_deleting_HDLC_channels></a>Adding and deleting HDLC 
 channels</h2>

<p>The NMS DLCP software provides NMS V5 library support for ISDN through 
 the V5.2 protocol. Supporting ISDN on V5.2 interfaces requires that applications 
 be able to dynamically add and remove ISDN channel locations to provisioned 
 interfaces.</p>

<p>Access network (AN) applications use the following functions to dynamically 
 add or delete HDLC channels that carry ISDN traffic over V5.2 interfaces: 
 </p>

<table cellpadding="5" x-use-null-cells cellspacing="0" border="1" class="whs2">

<tr bgcolor="#CCCCCC" valign="top" class="whs3">
<td class="whs4">
<p class="whs5">Function</p></td>
<td class="whs4">
<p class="whs5">Description</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p><a href="nmsv5addchannel.html"><span style="color: #0000ff;
												font-style: normal;
												font-weight: bold;
												x-text-underline: off;
												x-text-overline: off;
												x-text-line-through: off;
												text-transform: none;
												vertical-align: baseline;
												/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5AddChannel</B></font></span></a></p></td>
<td class="whs4">
<p>Adds an HDLC link (usually associated with ISDN data channel over V5.2 
 interface) to an active provisioned interface variant.</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p><a href="nmsv5deletechannel.html"><span style="color: #0000ff;
													font-style: normal;
													font-weight: bold;
													x-text-underline: off;
													x-text-overline: off;
													x-text-line-through: off;
													text-transform: none;
													vertical-align: baseline;
													/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DeleteChannel</B></font></span></a></p></td>
<td class="whs4">
<p>Deletes an HDLC link (usually associated with ISDN data channel over 
 V5.2 interface) from an active provisioned interface variant.</p></td></tr>
</table><br>

<p>Call <span style="font-weight: bold;"><B>NMS_V5AddChannel</B></span> or <span 
 style="font-weight: bold;"><B>NMS_V5DeleteChannel</B></span> when in the provisioned 
 and started state as shown in the <a href="#NMS V5 library state diagram">NMS 
 V5 library state model</a>.</p>

<p>Invoke <span style="font-weight: bold;"><B>NMS_V5AddChannel</B></span> or <span 
 style="font-weight: bold;"><B>NMS_V5DeleteChannel</B></span> only for HDLC channels 
 associated with a provisioned E1 link on a provisioned interface. When 
 the application invokes <span style="font-weight: bold;"><B>NMS_V5AddChannel</B></span> 
 for a started interface, the NMS V5 library automatically starts the new 
 HDLC link. After the new HDLC channel is added, the application can control 
 the channel as if it had been provisioned with <a href="nmsv5provisioninterface.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5ProvisionInterface</B></font></span></a>. 
 Applications do not need to stop provisioned interfaces before invoking 
 <a href="nmsv5deletechannel.html"><span style="color: #0000ff;
												font-weight: bold;
												x-text-underline: off;
												/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DeleteChannel</B></font></span></a>. 
 </p>

<p>Applications cannot use <span style="font-weight: bold;"><B>NMS_V5AddChannel</B></span> 
 or <span style="font-weight: bold;"><B>NMS_V5DeleteChannel</B></span> to<span 
 style="font-weight: bold;"> <B></B></span>add or delete HDLC channels associated 
 with the standby interface variants. To add or delete HDLC channels associated 
 with the standby interface variants, invoke <a href="nmsv5destroystandbyvariant.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DestroyStandByVariant</B></font></span></a> 
 and then re-provision the interface with <a href="nmsv5provisionstandbyvariant.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5ProvisionStandByVariant</B></font></span></a>.</p>

<h2><a name="Provisioning, switching to, and destroying a stand"></a>Provisioning, 
 switching to, and destroying a standby variant</h2>

<p>Invoke <a href="nmsv5provisionstandbyvariant.html"><span style="color: #0000ff;
	font-style: normal;
	font-weight: bold;
	x-text-underline: off;
	x-text-overline: off;
	x-text-line-through: off;
	text-transform: none;
	vertical-align: baseline;
	/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5ProvisionStandByVariant</B></font></span></a> 
 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. </p>

<p>To switch from the active NMS V5 interface<span style="font-weight: bold;"> 
 <B></B></span>to a standby variant, invoke <a href="nmsv5switchovervariantdata.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5SwitchOverVariantData</B></font></span></a>. 
 <span style="font-weight: bold;"><B>NMS_V5SwitchOverVariantData</B></span> 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 <a href="nmsv5startinterface.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5StartInterface</B></font></span></a> 
 to start the interface. </p>

<p class=Note><span style="font-weight: bold;"><B>Note: </B></span>Applications 
 should call <span style="font-weight: bold;"><B>NMS_V5SwitchOverVariantData</B></span> 
 after the upper level of the V5.2 (in this case, the AV5 stack) interface 
 has finished its switchover process.</p>

<p>To add or delete E1 links on a standby variant of an interface, you 
 must first destroy the standby variant with <a href="nmsv5destroystandbyvariant.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DestroyStandByVariant</B></font></span></a> 
 and then re-provision the variant with <span style="font-weight: bold;"><B>NMS_V5ProvisionStandByVariant</B></span>. 
 If the call to <span style="font-weight: bold;"><B>NMS_V5SwitchOverVariantData</B></span> 
 fails, both the active and the failed standby variants of the existing 
 interface are destroyed. The application must then invoke <a href="nmsv5destroyinterface.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DestroyInterface</B></font></span></a> 
 and <a href="nmsv5provisioninterface.html"><span style="color: #0000ff;
															font-weight: bold;
															x-text-underline: off;
															/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5ProvisionInterface</B></font></span></a> 
 to re-provision the interface.</p>

<h2><a name="Sending and receiving HDLC channel data"></a>Sending and receiving 
 HDLC channel data</h2>

<p>Use <a href="nmsv5phsenddata.html"><span style="color: #0000ff;
													font-style: normal;
													font-weight: bold;
													x-text-underline: off;
													x-text-overline: off;
													x-text-line-through: off;
													text-transform: none;
													vertical-align: baseline;
													/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5PhSendData</B></font></span></a> 
 to asynchronously send data to HDLC channels on a started interface. </p>

<p>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.</p>

<h2><a name="Monitoring E1 link status information"></a>Monitoring E1 link 
 status information</h2>

<p>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. </p>

<p>Use <a href="nmsv5gete1status.html"><span style="color: #0000ff;
													font-style: normal;
													font-weight: bold;
													x-text-underline: off;
													x-text-overline: off;
													x-text-line-through: off;
													text-transform: none;
													vertical-align: baseline;
													/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5GetE1Status</B></font></span></a><span 
 style="font-weight: bold;"> <B></B></span>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. You can also use <a href="nmsv5resete1status.html"><span 
 style="color: #0000ff;
		font-style: normal;
		font-weight: bold;
		x-text-underline: off;
		x-text-overline: off;
		x-text-line-through: off;
		text-transform: none;
		vertical-align: baseline;
		/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5ResetE1Status</B></font></span></a> 
 to reset the status information associated with an E1 link.</p>

<h2><a name="Controlling SA7 bit values on E1 links"></a>Controlling SA7 
 bit values on E1 links</h2>

<p>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. <a href="nmsv5sendsa7bit.html"><span style="color: #0000ff;
	font-style: normal;
	font-weight: bold;
	x-text-underline: off;
	x-text-overline: off;
	x-text-line-through: off;
	text-transform: none;
	vertical-align: baseline;
	/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5SendSA7Bit</B></font></span></a> 
 enables applications to set the SA7 bit value to 0 or 1 for a specified 
 E1 link. </p>

<h2><a name="Retrieving HDLC channel and E1 link status informa"></a>Retrieving 
 HDLC channel and E1 link status information</h2>

<p>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. Invoke <a href="nmsv5gete1status.html"><span style="color: #0000ff;
	font-weight: bold;
	x-text-underline: off;
	/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5GetE1Status</B></font></span></a> 
 to query E1 status information or invoke <a href="nmsv5getchannelstatistics.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5GetChannelStatistics</B></font></span></a> 
 to retrieve<span style="font-weight: bold;"> <B></B></span>HDLC channel statistics 
 for a particular HDLC channel. </p>

<p><span style="font-weight: bold;"><B>NMS_V5GetE1Status</B></span> returns current 
 E1 link status and error history information (collected over an elapsed 
 period of time). <span style="font-weight: bold;"><B>NMS_V5GetChannelStatistics</B></span> 
 reports success and error history information for both receive and transmit 
 directions on a specified HDLC channel.</p>

<p>To reset the HDLC channel statistics or E1 link status, call <a href="nmsv5resetchannelstatistics.html"><span 
 style="color: #0000ff;
		font-style: normal;
		font-weight: bold;
		x-text-underline: off;
		x-text-overline: off;
		x-text-line-through: off;
		text-transform: none;
		vertical-align: baseline;
		/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5ResetChannelStatistics</B></font></span></a> 
 or <a href="nmsv5resete1status.html"><span style="color: #0000ff;
													font-style: normal;
													font-weight: bold;
													x-text-underline: off;
													x-text-overline: off;
													x-text-line-through: off;
													text-transform: none;
													vertical-align: baseline;
													/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5ResetE1Status</B></font></span></a>.</p>

<h2><a name="Reprovisioning an existing interface"></a>Re-provisioning 
 an existing interface</h2>

<p>To re-provision an existing interface with NMS V5 library functions, 
 perform the following steps:</p>

<table cellpadding="5" x-use-null-cells cellspacing="0" width="100%" border="1" class="whs7">
<col class="whs8">
<col class="whs9">

<tr>
<td bgcolor="#CCCCCC" width="7.152%" class="whs10">
<p class="whs5">Step</p></td>
<td bgcolor="#CCCCCC" width="92.848%" class="whs11">
<p class="whs5">Action</p></td></tr>

<tr>
<td bgcolor="#FFFFFF" width="7.152%" class="whs12">
<p>1</p></td>
<td bgcolor="#FFFFFF" width="92.848%" class="whs13">
<p>Stop the interface (if the interface is started) with <a href="nmsv5stopinterface.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5StopInterface</B></font></span></a>.</p></td></tr>

<tr>
<td bgcolor="#FFFFFF" width="7.152%" class="whs12">
<p>2</p></td>
<td bgcolor="#FFFFFF" width="92.848%" class="whs13">
<p>Destroy the current interface with <a href="nmsv5destroyinterface.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DestroyInterface</B></font></span></a>. 
 This function destroys both the active and standby variants of the interface. 
 Destroyed E1 links have the SA7 framing bit set to 1.</p></td></tr>

<tr>
<td bgcolor="#FFFFFF" width="7.152%" class="whs12">
<p>3</p></td>
<td bgcolor="#FFFFFF" width="92.848%" class="whs13">
<p>Re-provision the interface by invoking <a href="nmsv5provisioninterface.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5ProvisionInterface</B></font></span></a>. 
 Provisioned E1 links have the SA7 framing bit set to 1.</p></td></tr>

<tr>
<td bgcolor="#FFFFFF" width="7.152%" class="whs12">
<p>4</p></td>
<td bgcolor="#FFFFFF" width="92.848%" class="whs13">
<p>Start the new interface with <a href="nmsv5startinterface.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5StartInterface</B></font></span></a>.</p></td></tr>
</table><br>

<h2><a name="Stopping an interface"></a>Stopping an interface</h2>

<p>Invoke <a href="nmsv5stopinterface.html"><span style="color: #0000ff;
															font-style: normal;
															font-weight: bold;
															x-text-underline: off;
															x-text-overline: off;
															x-text-line-through: off;
															text-transform: none;
															vertical-align: baseline;
															/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5StopInterface</B></font></span></a> 
 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. </p>

<p>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 reset these statistics. </p>

<p>To restart a stopped interface, invoke <a href="nmsv5startinterface.html" style="font-weight: bold;">NMS_V5StartInterface</a>.</p>

<h2><a name="Destroying an interface"></a>Destroying an interface</h2>

<p>Invoke <a href="nmsv5destroyinterface.html"><span style="color: #0000ff;
															font-style: normal;
															font-weight: bold;
															x-text-underline: off;
															x-text-overline: off;
															x-text-line-through: off;
															text-transform: none;
															vertical-align: baseline;
															/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DestroyInterface</B></font></span></a> 
 to destroy an interface. When the interface is destroyed, the flow of 
 HDLC data stops, and the NMS V5 library stops monitoring E1 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 
 have SA7 framing bit set to 1. </p>

<p>To destroy only the standby variant of an existing interface, invoke 
 <a href="nmsv5destroystandbyvariant.html"><span style="color: #0000ff;
														font-style: normal;
														font-weight: bold;
														x-text-underline: off;
														x-text-overline: off;
														x-text-line-through: off;
														text-transform: none;
														vertical-align: baseline;
														/*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DestroyStandByVariant</B></font></span></a>.</p>

<h2><a name="Exiting the NMS V5 library"></a>Exiting the NMS V5 library</h2>

<p>To exit the AN system, call <a href="nmsv5exit.html"><span style="color: #0000ff;
	font-weight: bold;
	x-text-underline: off;
	/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5Exit</B></font></span></a>. 
 When an application calls <span style="font-weight: bold;"><B>NMS_V5Exit</B></span>, 
 the NMS V5 library:</p>

<ul type="disc" class="whs1">
	
	<li class=kadov-p><p>Stops all provisioned HDLC channels.</p></li>
	
	<li class=kadov-p><p>Disables E1 link monitoring.</p></li>
	
	<li class=kadov-p><p>Resets the SA7 framing bit to 1 on all E1 links.</p></li>
	
	<li class=kadov-p><p>Destroys all provisioned interfaces.</p></li>
</ul>

<p>Exiting the AN application gracefully (that is, invoking <a href="nmsv5stopinterface.html"><span 
 style="color: #0000ff;
		font-weight: bold;
		x-text-underline: off;
		/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5StopInterface</B></font></span></a> 
 and <a href="nmsv5destroyinterface.html"><span style="color: #0000ff;
														font-weight: bold;
														x-text-underline: off;
														/*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/ "><font color=blue ><B>NMS_V5DestroyInterface</B></font></span></a> 
 before invoking <span style="font-weight: bold;"><B>NMS_V5Exit</B></span>) brings 
 the boards to a known state, and allows you to restart the application 
 without rebooting the boards.</p>

<h2><a name="NMS V5 library state diagram"></a>NMS V5 library state model</h2>

<p>The following illustration shows state transitions for interfaces controlled 
 through the NMS V5 library. You must comply with the illustrated conditions 
 when integrating NMS V5 library functions into AN applications.</p>

<p><img src="images/v5state.gif" width="484px" height="565px" border="0" class="img_whs14"> </p>

<p>The following table describes the NMS V5 library interface states: </p>

<table cellpadding="5" x-use-null-cells cellspacing="0" border="1" class="whs2">

<tr bgcolor="#CCCCCC" valign="top" class="whs3">
<td class="whs4">
<p class="whs5">State</p></td>
<td class="whs4">
<p class="whs5">Description</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p>Null</p></td>
<td class="whs4">
<p>The board is booted and initialized with the user configuration, but 
 the NMS V5 physical library is not loaded.</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p>Idle</p></td>
<td class="whs4">
<p>The NMS V5 library is initialized. No communication link is established 
 between the application and the boards. Library tracing can be configured.</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p>Provisioned</p></td>
<td class="whs4">
<p>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. </p>
<p>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.</p></td></tr>

<tr valign="top" class="whs6">
<td class="whs4">
<p>Started</p></td>
<td class="whs4">
<p>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.</p></td></tr>
</table><br>

<div placeholder id="footer" class="whs15">
 <p align="center" class="whs16">&nbsp;</p>
 <p align="center" class="whs16"><script type="text/javascript" language="JavaScript1.2">var mailSubject = 'Documentation link: ' + document.title;
var mailBody = 'Link to reference this topic:%0A %0A' + location.href;
var mailDisplay = '<img src="send_link.gif" border="0" alt="Send link to this topic">'; 
document.write( 
'<a href="mailto:Enter recipient email address' 
+ '?subject=' + escape(mailSubject) 
+ '&body=' + (mailBody) 
+ '">' + mailDisplay + '</a>' 
);</script></p>
 <p align="center" class="whs17">&#169; 
 Copyright 2009 Dialogic Corporation. All rights reserved.</p>
</div>
<script type="text/javascript" language="javascript1.2">
<!--
if (window.writeIntopicBar)
	writeIntopicBar(0);
//-->
</script>
</body>
</html>

