(Page 1 of 1 in this chapter)

Chapter 2

Using Point-to-Point Switching

2.1 Introduction
2.1.1 Point-to-Point Switching Terminology
2.1.2 Properties of Connections and Listeners
2.2 Point-to-Point Switching Connection Object
2.2.1 Creating a Connection
2.2.2 Setting the Talker for a Connection
2.2.3 Adding Listeners to a Connection
2.2.4 Removing Listeners from a Connection
2.2.5 Setting the Silence Pattern for a Connection
2.2.6 Opening a Connection
2.2.7 Closing a Connection
2.2.8 Destroying a Named Connection
2.3 Making One-Talker, One-Listener Connections
2.3.1 Making a Simplex Connection
2.3.2 Making a Duplex Connection
2.3.3 Making a Quad Connection
2.3.4 Disconnecting a Talker and a Listener
2.4 Restoring Initial Connections
2.5 Connection Transactions
2.5.1 Cancelling a Begin/Submit Transaction
2.6 Terminating a Point-to-Point Switching Client
2.7 Error Processing
2.8 PPX Hot Swap Support
2.8.1 Configuration for Unpopulated CompactPCI Slots
2.8.2 Client Connections
2.8.3 Switch Disabled Error
2.8.4 Switching Service Log Support

2.1 Introduction

This chapter provides a detailed explanation of the programming model for the Point-to-Point Switching service, and describes how to use it in a CT Access application. It also presents a brief overview of basic Point-to-Point Switching service concepts and terms.

An application can use the Point-to-Point Switching service to:

2.1.1 Point-to-Point Switching Terminology

The following terms define the basic elements of the Point-to-Point Switching service:
Term

 Definition

connection object

 An internal data structure, maintained by the PPX server, that is created when a switch connection is successfully opened. It records the state of the connection. In the Point-to-Point Switching service, a connection object can be considered to be an empty container until talkers and listeners are assigned to it.

connection handle

 An identifier for a specific connection object.

connection

 A logical path between two terminus entities. Within the Point-to-Point Switching service, a connection may have only one talker, but can support multiple listeners.

terminus

 A single access point to a switch block input or switch block output. A terminus contains a bus, a stream, and a timeslot.

talker

 The terminus that drives the output on the connection.

listener

 The terminus that receives input from the connection.

2.1.2 Properties of Connections and Listeners

Point-to-Point Switching connections and Point-to-Point Switching listeners have unique properties:

2.2 Point-to-Point Switching Connection Object

The fundamental element in the Point-to-Point Switching service is a connection object. A connection is basically a telephone call. Each connection can have one talker. The talker in the connection is driving the output for that connection. Each connection can have one or more listeners. The listeners are receiving the input from the connection.

Use the Point-to-Point Switching service to perform the following operations:

2.2.1 Creating a Connection

A connection is created by calling ppxCreateConnection with a CTA context. A handle (ppxhd) to the connection is returned. The connection handle is used to specify the connection when setting a talker or adding listeners to the connection. When a connection is initially created, there are no telephony bus timeslots associated with it.

A default idle bit pattern (a fixed 8-bit pattern) can be specified in the call to ppxCreateConnection. If there is no talker attached, any listeners added to the connection receive the default pattern sent on the stream attached to the listener.

In the following sections, an example application is used to demonstrate the Point-to-Point Switching functions. The example application runs a system in which incoming callers are placed on hold while waiting for an available operator. All callers that are on hold listen to the same voice message.

Figure 5 shows the creation of the connection, hold_message_block. A default pattern is set and a pointer to the connection is returned.

Figure 5. Creating a Connection Object



When creating a connection, you may assign a name to the connection. A named connection can be accessed by other applications, as discussed in Section 2.2.6, Opening a Connection.






2.2.2	 Setting the Talker for a Connection





ppxSetTalker sets a talker for a connection. The address of the talker is specified by the switch identification number, bus type (CTBUS, LOCAL, or MC1), stream, and timeslot.



If there are listeners already attached to the connection, the Point-to-Point Switching service connects the listeners to the talker using underlying switch connections. The switch connections may involve the allocation of bus timeslots if the talkers and the listeners are on different boards. If there was a talker already attached to the connection, the original talker is automatically disconnected before the new talker is connected.



In the example shown in Figure 6, the talker is added to the hold_message_block. The talker is a DSP resource playing the on-hold message.





Figure 6.	 Setting the Talker to a Connection






2.2.3	 Adding Listeners to a Connection





ppxAddListeners adds listeners to a connection. The listeners are specified by an array containing the switch identification number, bus type (CTBUS, LOCAL, or MC1), stream, and timeslot for each listener.



If the connection already has a talker attached, the listeners are connected to the talker using switch connections. The switch connections may involve the allocation of bus timeslots if the talker and the listener are on different boards. If there is no talker attached to the connection, the listeners have the default pattern of the connection sent to them.



In Figure 7, as incoming calls are received, they are connected to the hold_message_block to receive the on-hold message while waiting for an available operator.





Figure 7.	 Adding Listeners to a Connection






2.2.4	 Removing Listeners from a Connection





ppxRemoveListeners removes listeners from a connection. The listeners are specified by an array containing the switch identification number, bus type (CTBUS, LOCAL, or MC1), stream, and timeslot for each listener.



If the listeners are connected to a talker, the switch connections are broken. The listeners are put into their default disabled hardware state. For telephony bus output streams, the default hardware state is a high impedance state. Local bus output streams are put into the vendor-specified default state.



In the example shown in Figure 8, as an operator becomes available, listeners are removed from the hold_message_block so they can be connected to an operator.





Figure 8.	 Removing Listeners from a Connection






2.2.5	 Setting the Silence Pattern for a Connection





ppxSetDefaultPattern sets the default pattern for a connection. If there is no talker attached to a connection, the listeners receive the default pattern. If listeners are connected to a talker and the talker is removed, the listeners receive the default pattern for the connection.



This function overrides the default pattern set when the connection is created by calling ppxCreateConnection.  The default silence pattern used by the server is 0x7f (mu-law). This default value may be modified by setting a switch fabric attribute within the PPX configuration file, which is described in Chapter 3.






2.2.6	 Opening a Connection





ppxOpenConnection returns a handle to a named connection.



Typically, in CT Access, each application runs as a separate thread or process.If a connection is assigned a name when it is created, each application may open a handle to that connection and add a talker or add/remove listeners. Any action taken in one application is reflected in the connection which will be apparent in every application which accesses that connection.


Note:  The Point-to-Point Switching service considers a PPX client to be equivalent to an application.




Figure 9.	 Opening a Connection Handle




In Figure 9, the hold_message_block was created with the name hold_msg. In the system, one application is managing incoming calls and transferring them to operators when they are available. Another application is used to manage the operator stations. If an operator needs to place the caller back on-hold, the application can open the connection named hold_msg. The connection handle hold_message_block is returned and the application can then add the caller as a listener to that connection.






2.2.7	 Closing a Connection





ppxCloseConnection closes a previously created connection.



If the connection is unnamed (see Section 2.2.1, Creating a Connection for information about naming connections), the resources associated with the connection are freed and all connection outputs become disabled. A named connection is closed by ppxDestroyNamedConnection.






2.2.8	 Destroying a Named Connection





ppxDestroyNamedConnection frees all resources and disables outputs to all points on a named connection. Even if all applications close a named connection (via ppxCloseConnection), the connection remains in the Point-to-Point Switching connection database until it is explicitly destroyed (via ppxDestroyNamedConnection).



Once destroyed, any open handles to the named connection become invalid in all applications.






2.3	 Making One-Talker, One-Listener Connections





The Point-to-Point Switching service provides convenience functions, ppxConnect and ppxDisconnect, to make connections between one talker and one listener.



Connections made with ppxConnect use internal connection handles which cannot be accessed by the application. Additional listeners cannot be added to connections made with the convenience functions, nor can these connections be accessed across applications. 



When a connection is made using ppxConnect, the connection is "owned" by the CTA context which created it. The connection can only be disconnected (by calling ppxDisconnect) by the owner CTA context.



These convenience functions include a mode argument, which directs the Point-to-Point Switching service to calculate endpoints for any additional connections based upon the single talker and listener that have been passed. The mode argument can have any of the following values: 





 Value



 Description




 PPX_SIMPLEX



 Establishes a connection in one direction; this mode is typically used to broadcast, or to monitor half a conversation.




 PPX_DUPLEX



 Establishes connections in two directions; this mode is typically used to connect a phone conversation.




 PPX_QUAD



 Establishes two duplex connections, one for voice and one for signaling; this mode is typically used to connect two telephone channels.



















2.3.1	 Making a Simplex Connection





A simplex connection is made by calling ppxConnect and passing it the addresses of the talker and the listener, and the mode PPX_SIMPLEX. The Point-to-Point Switching service connects the talker to the listener by making the necessary switch connection. The connection may involve the allocation of telephony bus timeslots if the talker and the listener are on different boards.



For example, Figure 10 shows a simplex connection between local resources on a telephony board. The switch connection connects a network interface voice input on local stream 0 to the DSP voice output on local stream 5.





Figure 10.	 Simplex Connection






2.3.2	 Making a Duplex Connection





A duplex connection is made by calling ppxConnect and passing it the addresses of the talker and the listener, and the mode PPX_DUPLEX. For duplex connections, the Point-to-Point Switching service makes two end-to-end connections. The connections will involve the allocation of telephony bus timeslots if the talker and the listener are on different boards.



A duplex connection is a bidirectional voice or a bidirectional signaling connection. Telephony bus streams are typically defined in pairs; an even-numbered stream n has a corresponding stream n+1. The even-numbered stream is in one direction and the odd-numbered stream is in the other direction. For example, if stream 0 is an input stream, stream 1 is an output stream.



For a duplex Point-to-Point Switching connection, the first connection is specified by the talker and listener which are passed are arguments to the function. The second connection is determined by connecting the stream pair.



For example, Figure 11 shows a duplex connection between local resources on a telephony board. ppxConnect is called with the address of the talker (LOCAL:0:3) and the address of the listener (LOCAL:5:3). The first connection makes the connection between the talker and the listener. The Point-to-Point Switching service automatically makes the second connection which is LOCAL:4:3 (stream 4 is the pair of stream 5) to LOCAL:1:3 (stream 1 is the pair of stream 0).


 


Figure 11.	 Duplex Connection




The Point-to-Point Switching service uses the following algorithm to determine the streams which are used in a duplex connection. The application specifies one talker and one listener in the command:


  ppxConnect( ctahd, &talker, &listener, PPX_DUPLEX)




The Point-to-Point Switching service makes the following connections:






2.3.3	 Making a Quad Connection





A quad connection is made by calling ppxConnect and passing it the addresses of the talker and the listener, and the mode PPX_QUAD. A quad connection is the same as making two duplex connections. The Point-to-Point Switching service makes four end-to-end connections. The connections may involve the allocation of telephony bus timeslots if the talker and the listener are on different boards.



In a quad connection, the application specifies one connection, which connects a talker to a listener.



The Point-to-Point Switching service makes the following additional connections:




Figure 12 shows a quad connection between local resources on a telephony board. ppxConnect is called with the address of the talker (LOCAL:0:3) and the address of the listener (LOCAL:5:3). The first connection makes the connection between the talker and the listener. The second connection connects LOCAL:4:3 (stream 4 is the pair of stream 5) to LOCAL:1:3 (stream 1 is the pair of stream 0). The third connection makes the connection between the LOCAL:2:3 (stream 2 is stream 0 + 2) to LOCAL:7:3 (stream 7 is stream 5 + 2). The second connection connects LOCAL:6:3 (stream 6 is the pair of stream 7) to LOCAL:3:3 (stream 3 is the pair of stream 2).


.


Figure 12.	 Quad Connection




The Point-to-Point Switching service makes the required switch connections by calling ppxConnect with two endpoints.



For example, connecting a network interface to the on-board DSP resources for one channel on an AG-T1 consists of one Point-to-Point Switching call. The Point-to-Point Switching service makes four switch connections:


 





 Application



 Switch Connections Made by 


 Point-to-Point Switching Service




 talker.switch_number =0;
talker.bus = MVIP95_LOCAL_BUS;
talker.stream = 0;
talker.timeslot = 4;


 listener.switch_number = 0;
listener.bus = MVIP95_LOCAL_BUS;
listener.stream = 5;
listener.timeslot = 4;


 ppxConnect(ctahd, &talker, &listener, PPX_QUAD)


 



 talker.bus = MVIP95_LOCAL_BUS;
talker.stream = 0;
talker.timeslot = 4;


 listener.bus = MVIP95_LOCAL_BUS;
listener.stream = 5;
listener.timeslot = 4;


 swiMakeConnection(swihd, talker,listener,1)


 talker.bus = MVIP95_LOCAL_BUS;
talker.stream = 4;
talker.timeslot = 4;


 listener.bus = MVIP95_LOCAL_BUS;
listener.stream = 1;
listener.timeslot = 4;


 swiMakeConnection(swihd, talker,listener,1)


 talker.bus = MVIP95_LOCAL_BUS;
talker.stream = 2;
talker.timeslot = 4;


 listener.bus = MVIP95_LOCAL_BUS;
listener.stream = 7;
listener.timeslot = 4;


 swiMakeConnection(swihd, talker,listener,1)


 talker.bus = MVIP95_LOCAL_BUS;
talker.stream = 6;
talker.timeslot = 4;


 listener.bus = MVIP95_LOCAL_BUS;
listener.stream = 1;
listener.timeslot = 4;


 swiMakeConnection(swihd, talker,listener,1)

















Connecting the same network interface on the AG-T1 to DSP resources on an AG-8 board consists of only one Point-to-Point Switching call, but requires eight switch connections.






2.3.4	 Disconnecting a Talker and a Listener





ppxDisconnect is used to disconnect a previously connected simplex, duplex, or quad switch connection. Any intervening timeslots are freed. ppxDisconnect can only breakdown connections which are owned by the CTA context (i.e., the CTA context bound to the connection when it was created with ppxConnect).






2.4	 Restoring Initial Connections





Switch connections can be specified in the Point-to-Point Switching configuration file. These connections can be disconnected via ppxDisconnect if the connections were not specified with the NAILED keyword.



See Section 3.7, Specifying Switch Connections for details about connections made in the Point-to-Point Switching configuration file.



ppxRestoreConnections is used to set the Point-to-Point Switching service to restore the Point-to-Point Switching configuration file switch connections when the application exits.



If this function is not called, the switch connections are left in the state as modified by the application.






2.5	 Connection Transactions





Use the Point-to-Point Switching service to group switch commands into a single logical transaction. This functionality creates a batch of connections which are related to each other. All operations within the transaction must be completed successfully, or the transaction fails.



A group of switch operations starts with a ppxBegin command. Each Point-to-Point Switching function called after ppxBegin returns immediately, and the switch connections are not made until ppxSubmit is called.



ppxSubmit is an asynchronous function, but it returns immediately. The final result of the transaction will be delivered in an event. 



When ppxSubmit is called, the Point-to-Point Switching service determines if each operation is valid and that there are valid paths for all connections.



After verifying the commands and paths, the Point-to-Point Switching service calls the functions to perform the operations. If an error occurs when making the connections, any pending operations are aborted. The Point-to-Point Switching service restores any of the connections made up to that point and the system is returned to its state before ppxBegin was called.



When all connections have been made, the event PPXEVN_SUBMIT_COMPLETE is returned.



All Point-to-Point Switching functions except ppxOpenConnection and ppxCreateConnection functions can be included in a ppxBegin/ppxSubmit block. Only one ppxBegin/ppxSubmit block can be active on a given CTA context.






2.5.1	 Cancelling a Begin/Submit Transaction





ppxBeginCancel cancels a group of commands preceded by a ppxBegin statement.






2.6	 Terminating a Point-to-Point Switching Client 





The IPC mechanism, which the Point-to-Point Switching service uses to communicate between the Point-to-Point Switching client and the Point-to-Point Switching server, notifies the Point-to-Point Switching server when a client is no longer running. When a client stops running, all connections that the client had established during its lifetime are disconnected, and all associated resources are freed. A Point-to-Point Switching client does not need to perform explicit disconnections when it exits - unless it is bound to a named connection.



Named connections are not automatically disconnected. If a named connection was established or opened by the exiting client, the named connection remains unchanged at the client's exit; nothing is disconnected and no resources are freed. This connection persists until explicitly destroyed at a later time by a different Point-to-Point Switching client with ppxDestroyNamedConnection.






2.7	 Error Processing





If the PPX server encounters an error while processing a Point-to-Point Switching function call for a client, the Point-to-Point Switching connection database returns to its initial state at the time the function was initiated. The Point-to-Point Switching connection database returns to its initial state when either Point-to-Point Switching errors or Switching service errors occur during function processing (some Point-to-Point Switching functions call Switching service functions as part of normal execution). 



For example, if a new talker is set for a connection, the previous talker is disconnected from the listeners on the connection, and the new talker is connected to these listeners. If the connections fails while the new talker is being connected to any one of the listening points, the previous talker is reestablished on the connection. Any new connections established up to the point of the failure will be broken, and any previously existing connections (to the previous talker) will be restored.






2.8	 PPX Hot Swap Support





PPX can establish a set of connections based upon the presence of a "Connect" definition within its configuration file. Because of these connections, it is necessary that PPX is Hot Swap-aware. PPX must release resources for those initial connections that are using a switch associated with a Hot Swap service HSIEVN_REMOVAL_REQUESTED event.  See the Hot Swap Developer's Manual for more information.



The PPX server has a thread for receiving Hot Swap events. Upon receiving a removal event for a board that is used in one of these initial connections, PPX tears down the connection that is using the switch and marks the switch disabled within the fabric.



If the input on the connection (listener) is on an enabled switch, the default idle pattern is sent to the listening point.  This same action is taken when a NULL talker is assigned to a connection object to which listeners have already been assigned.



When an HSIEVN_BOARD_READY event is received, PPX determines whether  the board's switch was being used by one of the initial connections. If it was, the connection will be re-established. PPX will also set the state of the switch and local bus points to enabled status.






2.8.1	 Configuration for Unpopulated CompactPCI Slots





In the AG configuration file, users define boards for unpopulated CompactPCI slots. Similarly, the following PPX configuration is needed within the switch definition of boards that are planned to be inserted into currently unpopulated CompactPCI slots:


   SwitchState [ENABLED | DISABLED]




When the field is set to DISABLED, the switch will be added to the switching fabric, but its state will be set disabled.  The switch will not be used by PPX to create intermediate bus connections. Clients will receive an error when attempting to use the switch. If this field is missing from the definition of the switch, its value will be assumed ENABLED.






2.8.2	 Client Connections





Client applications are responsible for terminating connections that are effected by the occurrence of an HSIEVN_REMOVAL_REQUESTED event.  PPX will not close the switch handle until all clients have disconnected from the switch.  Until the switch has been closed, clients may continue to make connections using the switch.






2.8.3	 Switch Disabled Error





Subsequent to the switch being closed, users will be prevented from making connections that reference a switch which has become disabled.  The PPX error value, PPXERR_DISABLED, will be returned from the following API functions when a disabled switch is specified:


·	 ppxAddListeners


·	 ppxConnect




For more information on errors and events, see Appendix B.






2.8.4	 Switching Service Log Support





If PPX's SWI command logging has been configured, switch enable and disable information will appear in the log file.



In the following example, the subsequent SWI log information shows what would appear if each of the two boards (shown in the ppx.cfg excerpt) were removed and then reinserted.


ppx.cfg

[PPX]
Fabric
        
        # 
        Switch 1
            SwitchType = HMIC
            DeviceName = "agsw"
            DeviceNumber = 1

        #  etc...
        Switch 4
            SwitchType = HMIC
            DeviceName = "agsw"
            DeviceNumber = 4
       #  etc  
       
      # Initial Connections estabished by PPX server
      Connect
            1:local:0:0 to 1:local:17:0 QUAD
            4:local:0:2 to 4:local:17:2 QUAD 
        End Connect
End Fabric
ppxswi.log
Setup of initial connections.

[Tue Jan 12 15:29:11 1999] Switch 1: Handle Opened 0x1
[Tue Jan 12 15:29:11 1999]   swiMakeConnect: hd 0x1 LOCAL:0:0 TO LOCAL:17:0
[Tue Jan 12 15:29:11 1999]   swiMakeConnect: hd 0x1 LOCAL:16:0 TO LOCAL:1:0
[Tue Jan 12 15:29:11 1999]   swiMakeConnect: hd 0x1 LOCAL:2:0 TO LOCAL:19:0
[Tue Jan 12 15:29:11 1999]   swiMakeConnect: hd 0x1 LOCAL:18:0 TO LOCAL:3:0
[Tue Jan 12 15:29:12 1999] Switch 4: Handle Opened 0x10002
[Tue Jan 12 15:29:12 1999]   swiMakeConnect: hd 0x10002 LOCAL:0:2 TO
                             LOCAL:17:2
[Tue Jan 12 15:29:12 1999]   swiMakeConnect: hd 0x10002 LOCAL:16:2 TO 
                             LOCAL:1:2
[Tue Jan 12 15:29:12 1999]   swiMakeConnect: hd 0x10002 LOCAL:2:2 TO 
                             LOCAL:19:2
[Tue Jan 12 15:29:12 1999]   swiMakeConnect: hd 0x10002 LOCAL:18:2 TO 
                             LOCAL:3:2

Board removal 

[Tue Jan 12 15:30:39 1999] Switch 4 Device 4 DISABLED
[Tue Jan 12 15:30:39 1999] Switch 4 Handle 0x10002 Closed
[Tue Jan 12 15:30:43 1999] Switch 1 Device 1 DISABLED
[Tue Jan 12 15:30:43 1999] Switch 1 Handle 0x1 Closed

Reinsert with auto reconnect

reinsert:
[Tue Jan 12 15:30:52 1999] Switch 1 Device 1 ENABLED
[Tue Jan 12 15:30:52 1999] Switch 1: Handle Opened 0x20001

reconnect:
[Tue Jan 12 15:30:52 1999]   swiMakeConnect: hd 0x20001 LOCAL:0:0 TO 
                             LOCAL:17:0
[Tue Jan 12 15:30:52 1999]   swiMakeConnect: hd 0x20001 LOCAL:16:0 TO 
                             LOCAL:1:0
[Tue Jan 12 15:30:52 1999]   swiMakeConnect: hd 0x20001 LOCAL:2:0 TO 
                             LOCAL:19:0
[Tue Jan 12 15:30:52 1999]   swiMakeConnect: hd 0x20001 LOCAL:18:0 TO 
                             LOCAL:3:0

reinsert:
[Tue Jan 12 15:30:57 1999] Switch 4 Device 4 ENABLED
[Tue Jan 12 15:30:57 1999] Switch 4: Handle Opened 0x30002

reconnect:
[Tue Jan 12 15:30:57 1999]   swiMakeConnect: hd 0x30002 LOCAL:0:2 TO 
                             LOCAL:17:2
[Tue Jan 12 15:30:57 1999]   swiMakeConnect: hd 0x30002 LOCAL:16:2 TO 
                             LOCAL:1:2
[Tue Jan 12 15:30:57 1999]   swiMakeConnect: hd 0x30002 LOCAL:2:2 TO 
                             LOCAL:19:2
[Tue Jan 12 15:30:57 1999]   swiMakeConnect: hd 0x30002 LOCAL:18:2 TO 
                             LOCAL:3:2











 
    (Page 1 of 1 in this chapter)




 




tech_support@nmss.com



Copyright © 1999, Natural MicroSystems, Inc.   All rights
reserved.