1.1 Introduction

1.2 Point-to-Point Switching

1.3 About Natural Access

1.3.1 Operations, Administration, and Maintenance Service

1.4 Setting Up the Natural Access Environment

1.4.1 Initializing Natural Access

1.4.2 Creating Event Queues and Contexts

1.4.3 Opening Services

1.5 Using Point-to-Point Switching in a Natural Access Application

1.6 The Point-to-Point Switching Server

1.7 Using the PPX Server on Windows NT/Windows 2000

1.7.1 Controlling the PPX Server Manually

1.7.2 Using the PPX Server as a Windows NT/Windows 2000 Service

1.7.3 Starting and Stopping the PPX Server

1.7.4 Removing the PPX Server from Windows NT/Windows 2000 Services

1.8 Using the PPX Server on UNIX

1.8.1 Starting the PPX Server

1.8.2 Stopping the PPX Server

1.9 Using the PPX Initialization Error Log

1.10 Communications Port Number

1.11 SWI Error Logging

1.11.1 A Sample ppxswi.log

1.1 Introduction

The Point-to-Point Switching Service Developer's Reference Manual provides:

• An overview of the Natural Access Point-to-Point Switching (PPX) service.

• A reference of its functions and errors.

This manual defines telephony terms where applicable, but assumes that the reader is familiar with telephony and switching concepts, and with the C programming language.

Read the Natural Access Developer's Reference Manual before using this manual. The Natural Access Developer's Reference Manual contains detailed information about Natural Access concepts, architecture, and application development. This information must be fully understood before you develop a switching application using Natural Access.

1.2 Point-to-Point Switching

This chapter:

• Explains the Point-to-Point Switching (PPX) service.

• Provides background information about using the Natural Access development environment.

• Provides instructions for using the Point-to-Point Switching service in a Natural Access application.

• Provides detailed information about using the PPX server, including its error logging.

The Point-to-Point Switching service provides an application programming interface (API) for making switch connections between boards connected by a telephony bus without having to specify the intervening bus timeslots. The Point-to-Point Switching service maintains an internal database that records the topology of the switching configuration for the system and the state of all the timeslots.

When making a switch connection using Point-to-Point Switching, you specify the two endpoints for the connection. The Point-to-Point Switching service manages the telephony bus timeslots and controls the underlying hardware switches to make the connections. The Point-to-Point Switching service can be used with any board that has an FMIC or HMIC type switch.

In the example system shown in Figure 1, a connection is required between a DSP resource on an AG 4000 board and a T1 channel on an AG Quad T board. The DSP resource on the AG 4000 is being used to play an on hold message for all incoming calls.

Figure 1. An Example of a System Using Switching

Using the Point-to-Point Switching service, the application calls one function specifying the location of the DSP resource (for example, board number, local stream and timeslot) and the location of the caller (for example, board number, local stream and timeslot). The PPX Switching service determines the required telephony bus timeslots and makes the necessary switch connections.

In contrast, using Natural Access Switching service (SWI) functions to make the connection, an application is required to:

1. Determine if the switch connection can use the local bus or if it requires telephony bus timeslots.

2. Determine which telephony bus timeslots are available for the connection.

3. Send the switch commands to connect the caller to an available timeslot on the telephony bus.
   
   
   Figure 2. Connecting the Caller to the Telephony Bus

4. Send the switch commands to connect the DSP resources to the telephony bus.
   
   
   Figure 3. Connecting the DSP Resources to the Telephony Bus

1.3 About Natural Access

The Point-to-Point Switching service is a Natural Access service. Natural Access is a development environment that provides hardware independent standard programming interfaces.

A Natural Access service is a group of logically related telephony functions. A service manager is a software wrapper that surrounds one or more services. It implements the required Natural Access functions that enable a service to seamlessly integrate with Natural Access.

1.3.1 Operations, Administration, and Maintenance Service

The Operations, Administration, and Maintenance (OAM) service is the API for the NMS OAM software. NMS OAM is a Natural Access service that performs operations on, administration of, and maintenance of telephony resources in a system. Use NMS OAM to configure and initialize the NMS hardware in your chassis. NMS OAM can manage:

• Hardware components, such as NMS boards, or

• Software components, such as the NMS Hot Swap process.

Since these components are managed by NMS OAM, they are called managed components.

Using NMS OAM, you can:

• Create, delete, and query the configuration of a board-managed component.

• Start (boot), stop (shut down), and test a managed component.

• Receive notifications from managed components.

Software processes supported by NMS OAM include:

• Hot Swap: the ability to insert and extract CompactPCI boards without powering down the system.

• Basic H.110 clock management operations: configuring and setting the bus clock across all boards in a system.

NMS OAM is available with Natural Access 4.0 and later. For general information about NMS OAM, refer to the NMS OAM System User's Manual. For more information about the OAM service, refer to the NMS OAM Service Developer's Reference Manual.

Note: NMS OAM operates only when the Natural Access Server (ctdaemon) is running.

1.4 Setting Up the Natural Access Environment

Before you can call PPX functions, the application must initialize Natural Access and open the PPX Switching service. Application setup for Natural Access consists of the following steps:

1. Initializing Natural Access for the process.

2. Creating event queues.

3. Creating contexts and attaching them to an event queue.

4. Opening services on each context.

1.4.1 Initializing Natural Access

Register services in the call to ctaInitialize by specifying the service name and the service manager name. Only the services initialized in the call to ctaInitialize may be opened by the application.

1.4.2 Creating Event Queues and Contexts

After initializing Natural Access, create the event queues and contexts.

A context organizes services and accompanying resources around a single processing context. A context usually represents an application instance controlling a single telephone call.

Natural Access provides multi-processing support. Multiple Natural Access application processes can perform tasks on behalf of the same context (referred to as context sharing). Natural Access applications can transfer control of contexts (for example, contexts associated with individual telephone calls) to other Natural Access applications (referred to as context hand-off).

An event queue is the communication path from a Natural Access service to an application. A Natural Access service generates events indicating certain conditions or state changes. An application retrieves the events from the event queue. All Point-to-Point Switching functions are synchronous. Synchronous functions return when the function is complete and do not generate events.

Create one or more event queues by calling ctaCreateQueue. You specify which service managers will be attached to each queue. When you attach or bind a service manager to a queue, you make that service manager available to the queue.

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

1.4.3 Opening Services

Services are opened on a context by calling ctaOpenServices and passing a context handle and a list of service descriptors. A service descriptor specifies the name of the service, service manager, and service-specific arguments.

The Point-to-Point Switching service does not require any service-specific arguments.

Note: It is not necessary to open the Natural Access Switching service (SWI) in a Point-to-Point Switching client application unless the application is making calls directly to SWI on its own behalf. For example, if the Point-to-Point Switching client application sets the telephony bus clocks and stream speeds, it would use SWI functions and, therefore, need to open the Switching service.

Refer to the Natural Access Developer's Reference Manual for details on initializing Natural Access and for programming models you can use.

1.5 Using Point-to-Point Switching in a Natural Access Application

The Point-to-Point Switching service provides functions for making switch connections. When using the Point-to-Point Switching service, all streams and timeslots are addressed using the MVIP-95 switch model.

The Natural Access Switching service provides additional functions for configuring telephony bus clocks and stream speed. Use these commands to configure the bus before making any connections. See the Switching Service Developer's Reference Manual for more information.

WARNING:

When using the Point-to-Point Switching service, do not use the Switching service to make switch connections. The Point-to-Point Switching service maintains an internal connection database to determine local resource and telephony bus usage. Since connections made with the Switching service are not recorded in this database, you may have unpredictable results. The Point-to-Point Switching service could use timeslots already used by the Switching service and the Switching service could use timeslots already used by the Point-to-Point Switching service.

1.6 The Point-to-Point Switching Server

Since the same telephony bus can be used in separate Natural Access applications, the Point-to-Point Switching service must be able to manage the bus streams and timeslots across multiple applications. Each instance of the Point-to-Point Switching service that is opened on a context runs as a client to a PPX server. The PPX server (ppxserv) manages an internal connection database to determine which timeslots are available on the telephony bus and what connections have been made in the system.

As shown in Figure 4, each application creates a context containing the
Point-to-Point Switching service, the ADI service, and the Switching service. Opening the Point-to-Point Switching service on the context creates an instance of a client to the PPX server. Each PPX client can be a separate process, but it is not required. A unique PPX client can be associated with each thread running in a single process.

All commands sent by the applications to the Point-to-Point Switching service are sent by the clients to the PPX server. The PPX server sends the commands to the board using the Switching service functions. Each application does not have to open the Switching service on a context. The PPX server automatically opens an instance of the Switching service.

Figure 4. Point-to-Point Switching Server

Before you start up the PPX server:

• Start the Natural Access daemon (ctdaemon).

• Ensure the boards are booted (run oamsys).

• Make sure the system switching topology (switch fabric) is defined in the Point-to-Point Switching configuration file. See Chapter 3 for details on creating the Point-to-Point Switching configuration file.

The Point-to-Point Switching server must be running while any application using the Point-to-Point Switching service is running.

The following table lists the PPX service deliverables:

File	Description
NT: \nms\bin\ppxapi.dll UNIX: /opt/nms/bin/libppxapi.so	Point-to-Point Switching service (PPX) interface library
NT: \nms\bin\ppxmgr.dll UNIX: /opt/nms/bin/libppxmgr.so	PPX service manager library
NT: \nms\bin\ppxserv.exe UNIX: /opt/nms/bin/ppxserv	PPX server
NT: \nms\bin\ppxservice.exe	PPX server as Windows NT/Windows 2000 service
NT: \nms\bin\ppxservicecfg.exe	Configures PPX server as Windows NT/Windows 2000
NT: \nms\bin\ppxstop.exe UNIX: /opt/nms/bin/ppxstop	Utility to shutdown PPX server
NT: \nms\ctaccess\cfg\ppx_tmpl.cfg UNIX: /opt/nms/ctaccess/cfg/ppx_tmpl.cfg	PPX service example configuration file
NT: \nms\ctaccess\demos\brd2brd\brd2brd.exe UNIX: /opt/nms/ctaccess/demos/brd2brd/brd2brd	Demo for PPX service
NT: \nms\ctaccess\demos\brd2brd\brd2brd.c UNIX: /opt/nms/ctaccess/demos/brd2brd/brd2brd.c	Demo source code
NT: \nms\ctaccess\demos\brd2brd\makefile UNIX: /opt/nms/ctaccess/demos/brd2brd/makefile	Makefile for compiling demo
NT: \nms\ctaccess\demos\callcntr\callcntr.exe UNIX: /opt/nms/ctaccess/demos/callcntr/callcntr	Demo for PPX service
NT: \nms\ctaccess\demos\callcntr\callcntr.c UNIX: /opt/nms/ctaccess/demos/callcntr/callcntr.c	Demo source code
NT: \nms\ctaccess\demos\callcntr\makefile UNIX: /opt/nms/ctaccess/demos/callcntr/makefile	Makefile for compiling demo
NT: \nms\include\ppxdef.h UNIX: /opt/nms/include/ppxdef.h	Header file for PPX service
NT: \nms\lib\ppxapi.lib	PPX service interface import library
NT: \nms\lib\ppxmgr.lib	PPX service manager import library

The PPX service deliverables include two libraries:

• A service interface library

• A service implementation library

The PPX service interface library consists of:

• Windows NT/Windows 2000: ppxapi.dll, ppxapi.lib

• UNIX: libppxapi.so

The PPX service implementation library consists of:

• Windows NT/Windows 2000: ppxmgr.dll, ppxmgr.lib

• UNIX: libppxmgr.so
  Note: Applications must link with the service interface library.

The Point-to-Point Switching service is shipped with a template configuration file (ppx_tmpl.cfg) that contains examples for the various NMS board types. Copy this template to the default configuration file (ppx.cfg) and modify it to represent your system. Or, modify the file, give it a unique name, and specify the name at startup using the -f option.

1.7 Using the PPX Server on Windows NT/Windows 2000

This section provides instructions for using the PPX server (ppxserv) on Windows NT/Windows 2000.

1.7.1 Controlling the PPX Server Manually

During system development and debugging of the Point-to-Point Switching configuration file, control the PPX server manually so it can be restarted as needed.

To start the PPX server from the command line, enter:

   start ppxserv [options]

where options are:

Option	Description
-f filename	Specifies the configuration filename. Default = \nms\ctacess\cfg\ppx.cfg
-e filename	Specifies the error log filename. Default = \nms\ctaccess\cfg\pxerror.log
-d filename	Specifies the database output filename. Default = \nms\ctaccess\ppxdb.log
-l	Turns on the SWI command logging process. Default = OFF
-w number	Specifies the line number at which the SWI log file will wrap to start. Default = 2000
-s filename	Specifies the SWI command log filename. Default = \nms\ctaccess\ppxswi.log

To stop the PPX server from the command line, enter:

   ppxstop

Use the ppxstop utility whenever the server needs to be stopped. This allows the server to terminate any connections it has established and to release communication resources.

1.7.2 Using the PPX Server as a Windows NT/Windows 2000 Service

Once the Point-to-Point Switching configuration file is verified, install the PPX server as a Windows NT/Windows 2000 service using the ppxservicecfg utility. See Section 6.6 for more information on using ppxservicecfg.

If there are connections specified in the PPX configuration file, all switching drivers must be accessible when PPX is initializing. This requires that the boards are loaded and running before the PPX service is started. For more information about OAM, see the OAM System User's Manual.

Before you run the PPX server, make sure there is a valid Point-to-Point Switching configuration file.

Once the PPX server is installed in the Windows NT/Windows 2000 registry, run the PPX server as follows:

1. Select Services from the Control Panel.

2. Highlight Point-to-Point Telephony Switching.

3. Select Start or Stop to manually start or stop the PPX server.

4. Select Startup/Automatic as the startup option to automatically start the PPX server when the system reboots.

1.7.3 Starting and Stopping the PPX Server

The PPX server can be controlled from the command line after it is installed as a Windows NT/Windows 2000 service. Before stopping the PPX server, shut down all client applications so that all switch connections created by the Point-to-Point Switching clients are automatically broken by the PPX server.

• To start the PPX server from the command line enter:

     net start ppx
  
  

• To stop the PPX server from the command line enter:

     ppxstop
  
  

1.7.4 Removing the PPX Server from Windows NT/Windows 2000 Services

To remove the PPX service and reset the Windows NT/Windows 2000 registry, enter:

  ppxservicecfg -remove

1.8 Using the PPX Server on UNIX

This section provides instructions for using the PPX server (ppxserv) on UNIX.

1.8.1 Starting the PPX Server

Before starting the PPX server, make sure there is a valid Point-to-Point Switching configuration file.

To start the PPX server:

1. Log in as root.

2. Enter the following:

      /opt/nms/bin/ppxserv [options]
   
   

   where options are:

   Option	Description
   -b	Forces the PPX server to run as a background process. Used instead of & to ensure that the server detaches from the console window at initialization.
   -p	Starts the PPX server with Hot Swap event monitoring. Used if the PPX service is configured to set up connections on swappable boards.
   -f filename	Specifies the configuration filename. Default = /var/opt/nms/ctaccess/cfg/ppx.cfg
   -e filename	Specifies the error log filename. Default = /var/opt/nms/ctaccess/ppxerror.log
   -d filename	Specifies the database output filename. Default = /var/opt/nms/ctaccess/ppxdb.log
   -l	Turns on the SWI command logging process. Default = OFF
   -w number	Specifies the line number at which the SWI log file will wrap to start. Default = 2000
   -s filename	Specifies the SWI command log filename. Default = /var/opt/nms/ctaccess/ppxswi.log

1.8.2 Stopping the PPX Server

Before stopping the PPX server, shut down all client applications so that all switch connections created by the Point-to-Point Switching clients are automatically broken by the PPX server.

Run the ppxstop utility whenever the server needs to be stopped. This allows the server to terminate any connections it has established and release communication resources.

1.9 Using the PPX Initialization Error Log

The PPX server creates an error log file when it is initialized. This error file records initialization errors and problems associated with the interpretation of the Point-to-Point Switching configuration file (ppx.cfg). By default, this error file is located as follows:

• Windows NT/Windows 2000: \nms\ctaccess\ppxerror.log

• UNIX: /var/opt/nms/ctaccess/ppxerror.log
  Note: If the PPX server terminates abnormally, any switch connections it has established at that time remain in place. Restarting the PPX server will not clear these underlying switch connections. Use the swish utility to reset the switches. For example, for an AG 2000 board, start up swish and enter the
  following:

      openswitch  s0 = agsw 0
      resetswitch s0
  

1.10 Communications Port Number

Natural Access applications use the Point-to-Point Switching service API to communicate with the PPX server (ppxserv). The communications mechanism is socket-based and the default port number used is 1110. If you see PPXERR_COMM_FAILURE in the PPX error log when you start up your Natural Access application, change the port number to an unused port number.

To change the port number:

1. Review your system configuration and determine a new port number to use.

2. Set the NMS_PPX_COMM environment variable to the new port number, using the appropriate mechanism for your operating system and shell.

3. Restart the PPX server and all applications.

1.11 SWI Error Logging

The Point-to-Point Switching service is a layer of software built on top of the Switching service. It uses the following Switching service functions:

• swiOpenSwitch

• swiMakeConnection

• swiDisableOutput

• swiSendPattern

• swiCloseSwitch

The Point-to-Point Switching service can log all Switching service function calls to a PPX Switching log file if you pass an optional parameter when you start the PPX server. It records all Switching service function calls the PPX server makes and includes an error indicator when necessary. The error indicator is an asterisk (*) and the actual value from the Switching service is at the end of the line.

The PPX/Switching log file is located and named as follows:

• Windows NT/Windows 2000: \nms\ctaccess\ppxswi.log

• UNIX: /var/opt/nms/ctaccess/ppxswi.log

The log file is circular, which prevents excessive use of disk space. By default, the log file contains the last 2000 Switching service calls made by the PPX server. The Switching service calls are time-stamped so you can track starting and ending points.

To start the PPX server and enable Switching service logging:

• Start the PPX server from the command line with the argument -l

To change the default number of SWI log entries stored in the log:

• Start the PPX server from the command line, with the arguments
  -l -w new_value

For example:

To restrict SWI logging to 10,000 entries on a Windows NT/Windows 2000 system:

• From the command line, enter:
  start \nms\bin\ppxserv -l -w 10000

To perform the same modification on a UNIX system:

1. Log in as root.

2. Start the PPX server in the background by entering:

      /opt/nms/bin/ppxserv -l -w 10000 -b
   
   

   Note: When you restart the PPX server with logging enabled, it overwrites any existing PPX Switching log files on the system. If you need to preserve your data, back up the log file using a different file name before you restart the PPX server.

1.11.1 A Sample ppxswi.log

This section provides an excerpt from a ppxswi.log file. The PPX server internally shares open switch handles among all client instances.

Note: The ret: value that appears on the line marked by an asterisk is the error return value from the Switching service.

Because the log file is circular, the date-stamp and the time-stamp of each issued command are recorded so you can identify the most recent entries after the file reaches its maximum capacity.

[Fri Jan 22 10:00:20 1999] Switch 0: Handle Opened 0x1
[Fri Jan 22 10:00:20 1999]   swiMakeConnect: hd 0x1 LOCAL:0:2 TO LOCAL:5:2
[Fri Jan 22 10:00:20 1999]   swiMakeConnect: hd 0x1 LOCAL:4:2 TO LOCAL:1:2
[Fri Jan 22 10:00:20 1999]   swiMakeConnect: hd 0x1 LOCAL:2:2 TO LOCAL:7:2
[Fri Jan 22 10:00:20 1999]   swiMakeConnect: hd 0x1 LOCAL:6:2 TO LOCAL:3:2
[Fri Jan 22 10:00:20 1999]   swiMakeConnect: hd 0x1 LOCAL:0:4 TO LOCAL:5:4
[Fri Jan 22 10:00:20 1999]   swiMakeConnect: hd 0x1 LOCAL:4:4 TO LOCAL:1:4
[Fri Jan 22 10:02:44 1999]   swiMakeConnect: hd 0x1 LOCAL:0:6 TO LOCAL:5:6
[Fri Jan 22 10:03:09 1999] Switch 1: Handle Opened 0x10002
[Fri Jan 22 10:03:09 1999]   swiMakeConnect: hd 0x10002 CTBUS:0:31 TO
                             LOCAL:1:6
[Fri Jan 22 10:03:09 1999]   swiMakeConnect: hd 0x1 LOCAL:0:6 TO CTBUS:0:31
[Fri Jan 22 10:03:14 1999]   swiMakeConnect: hd 0x10002 CTBUS:0:31 TO
                             LOCAL:1:4
[Fri Jan 22 10:07:47 1999]   swiMakeConnect: hd 0x10002 LOCAL:0:0 TO
                             CTBUS:5:0
[Fri Jan 22 10:53:24 1999]   swiDisableOutput: hd 0x10002 CTBUS:5:0
[Fri Jan 22 10:54:03 1999] * swiMakeConnect: hd 0x1 LOCAL:8:0 TO CTBUS:8:0
                             ret: 0x40004