• 2.3.1. Device Initialization Hint
• 2.3.2. Component Interoperation
• 2.3.3. Board Device Names and Numbers
• 2.3.4. Compatibility of Device Names/Numbers
• 2.3.5. Determining Channel Capabilities in Flexible Routing Configurations
• ft_front_end Feature Defines
• 2.3.6. Getting, Using, and Closing Device Handles in a DM3 Flexible Routing Configuration

2.3. Configuration, Initialization, and Operation

This section describes important information related to the configuration, start-up, and operation of R4 for DM3.

2.3.1. Device Initialization Hint

The xx_open( ) functions for the Voice (dx), GlobalCall (gc), Network (dt), and Fax (fx) APIs are asynchronous in this release of R4 on DM3, unlike the standard R4 versions, which are synchronous. This should usually have no impact on an application, except in cases where a subsequent function calls on a device that is still initializing, that is, is in the process of opening. In such cases, the initialization must be finished before the follow-up function can work. The function won't return an error, but it is blocked until the device is initialized.

For instance, if your application called the following two functions:

dx_open( )
  
dx_getfeaturelist( )

The dx_getfeaturelist( ) is blocked until the initialization of the device is completed internally, even though dx_open( ) has already returned success. In other words, the initialization (dx_open) may appear to be complete, but, in truth, it is still going on in parallel.

With some applications, this may cause slow device-initialization performance. Fortunately, you can avoid this particular problem quite simply by reorganizing the way the application opens and then configures devices. The recommendation is to do all xx_open( ) functions for all channels before proceeding with the next function. For example, you would have one loop through the system devices to do all the xx_open( ) functions first, and then start a second loop through the devices to configure them, instead of doing one single loop where a xx_open( ) is immediately followed by other API functions on the same device. With this method, by the time all xx_open( ) commands are completed, the first channel will be initialized, so you won't experience problems.

This change is not necessary for all applications, but if you experience poor initialization performance, you can gain back speed by using this hint.

2.3.2. Component Interoperation

Media Loads

Different configurations for DM3 products are supported in the form of media loads. For instance, a specific media load is available for users who need to implement CSP and conferencing in their applications. See the Release Guide for specific media loads available with this release.

R4 for DM3 Interoperability with R4

• R4 for DM3 can be installed and operated in a computer with existing R4 applications without affecting those applications; however, when the computer contains both DM3 and earlier-generation devices (such as Dialog/HD), the sr_getboardcnt( ) function will return the count for both types of devices in Windows. In Linux, use SRL device mapper functions to return information about the structure of the system. These functions are described in the Voice Software Reference - Standard Run-time Library.
• A single R4 application program can be written or modified to use both DM3 and earlier-generation devices (such as Dialog/HD) together in one system.
• The DM3 clustering method of voice resource and network interface timeslots implemented in the R4 API for DM3 is consistent with the clustering operation used in the DM3 embedded platform interface known as the DM3 Direct Interface (MDI). See Chapter 12. R4 on DM3 Resource Routing and Cluster Configuration for a description of DM3 clusters.

R4 for DM3 Interoperability with Other APIs/Interfaces

• R4 for DM3 can coexist (can be installed and can reside in a single PC) along with other software APIs or interfaces, such as the DM3 Application Foundation Code (AFC) and the DM3 embedded platform interface known as the DM3 Direct Interface (MDI).
• As with the R4 API, application programs designed with these APIs cannot run simultaneously unless each application uses its own set of unique DM3 components. Resource sharing between different applications is not supported due to the lack of a central resource manager to control access to the components.

2.3.3. Board Device Names and Numbers

As usual, board device names are assigned during the Dialogic Service initialization process. The Service uses the standard R4 naming conventions and numbering sequence for DM3 devices that are in the system configuration. (See the System Release Installation and Configuration Guide for full details on the R4 device-naming conventions.)

The following conventions apply to DM3 board naming and numbering for R4:

• All DM3 board devices are assigned standard device names for R4; for example, dxxxB1, dxxxB2, dtiB1, dtiB2.
• All DM3 channel and timeslot devices are assigned standard device names for R4; for example, dxxxB1C1, dxxxB1C2, dtiB1T1, dtiB1T2.
• A single physical DM3 board device can contain multiple "virtual boards" that are each numbered in sequential order; for example, a DM/V960-4T1 QuadSpan board with four digital network interfaces contains four virtual network interface boards that would follow a sequential numbering pattern such as dtiB1, dtiB2, dtiB3, dtiB4.
• In Windows, all DM3 board devices are numbered in sequential order after the earlier-generation devices (e.g., Dialog/HD boards) are numbered.
  
  Windows Naming Example:
  DM3: dtiB2 - dtiB5 / dxxxB7 - dxxxB30
  Springware: dtiB1 / dxxxB1 - dxxxB6
• In Linux, if all boards download properly, DM3 boards are named first and earlier-generation boards are named second. This is the reverse of Windows. To handle this naming convention, ensure your configuration files are set up so that your device names point to the proper boards. For example, take a system with a SpringWare board and a DM3 board.
  
  Linux Naming Example:
  DM3: dtiB1 - dtiB4 / dxxxB1 - dxxxB24
  Springware: dtiB5 / dxxxB25 - dxxxB30
• All DM3 board devices are numbered in sequential order based on the logical Board ID assigned by the DM3 driver (the board having the lowest logical Board ID will be assigned the next board number, and so on).
• In Windows, when R4 for DM3 is installed on a computer containing both DM3 and earlier-generation devices (such as Dialog/HD), the sr_getboardcnt( ) function when called with DEV_CLASS_VOICE returns a count of all voice board devices including DM3 boards. When called with DEV_CLASS_DTI, it returns a count of all DTI board devices including DM3 boards.
• In Linux, when R4 for DM3 is installed on a computer containing both DM3 and earlier-generation devices (such as Dialog/HD), use SRL device mapper functions to return information about the structure of the system. These functions are described in the Voice Software Reference - Standard Run-time Library.
• For an illustration of these device numbering conventions, see Table 1. Example of Assigned Device Names and Numbers.

2.3.4. Compatibility of Device Names/Numbers

Although there is consistency among different types of compatible Dialogic hardware in how devices are numbered, device mapping (device naming or device numbering) is hardware dependent. If a programmer "hard-codes" an application to use device names based on specific Dialogic boards, some of those device names may need to be changed if a different model board is used as a replacement. You can achieve the greatest degree of backward compatibility among Dialogic boards by making the device mapping in the application program hardware independent. The method for achieving this, along with sample application code, is provided in the Technical Note entitled "Identifying the number and type of Dialogic boards in a Windows NT system from within an application," which is found at http://support.dialogic.com/tnotes/tnbyos/winnt/tn193.htm. It can also be accessed through the Dialogic technical support web site at http://support.dialogic.com by selecting Answers, then Tech Notes, and then the operating system, "Win NT."

NOTE:

DM3 E1 dxxx channels are allocated contiguously. On earlier-generation products , they are allocated with a 2-channel gap. For example, with earlier-generation products, the names dxxxB1C1-dxxxB8C2 would be assigned for the first card and dxxxB9C1-dxxxB16C2 for the second card in a system. Notice that device names dxxxB8C3 and dxxxB8C4 do not exist. By contrast, for a DM3 DualSpan E1, the naming convention is contiguous: dxxxB1C1-dxxxB15C4.

2.3.5. Determining Channel Capabilities in Flexible Routing Configurations

There are three different types of voice devices: the ISDN compatible (all), the T1 CAS compatible, and the E1 CAS compatible. The T1 CAS compatible is a superset of ISDN compatible, and E1 CAS compatible is a superset of T1 CAS compatible.

When using GlobalCall, only certain DM3 network interfaces can be attached to certain other DM3 voice devices using gc_Attach( ), gc_Open( ) or gc_OpenEx( ). Attaching DM3 devices together depends on the network protocol used and voice device capabilities. Specifically:

• A DM3 ISDN network device can be attached to any DM3 voice device.
• A DM3 T1 CAS network device must be attached to a T1 CAS compatible DM3 voice device.
• A DM3 E1 CAS network device must be attached to an E1 CAS compatible DM3 voice device.

When using GlobalCall, if a voice device is not CAS or R2MF capable, it cannot be attached (in the attach call or in the open call) to a network interface device that has CAS or R2MF loaded. Likewise, if a voice device is not routable, it cannot be used in a gc_Attach( ) call.

While a network interface protocol cannot be determined programmatically, the function dx_getfeaturelist( ) provides a programmatic way of determining voice capability so that the application can make decisions. dx_getfeaturelist( ) returns bitmask information about the type of front end it can support, meaning ISDN, CAS (T1 CAS), R2MF (E1 CAS), or a combination thereof. Since the information is returned as a bitmask, each is independent of the other, so you can expect to get one and/or the other bitmask.

ft_front_end Feature Defines

The following have been added to the dxxxlib.h under the FrontEnd (ft_front_end) feature defines:

FT_ROUTEABLE  
FT_ISDN  
FT_CAS  
FT_R2MF

The ft_front_end feature defines in the dxxxlib.h header may contain the above four possible values. Note that for fixed routing, the FT_ROUTEABLE is not set, so none of the other bits is set. For flexible routing, the FT_ROUTEABLE bit is set, and the other three bits are set based on cluster contents.

For instance, if the ft_front_end bitmask is FT_ROUTEABLE | FT_ISDN | FT_CAS, this means that the channel is capable of flexible routing and can also work with an ISDN or a CAS (T1) frontend. In this example, R2MF is missing, so the channel cannot work with a front-end that is R2MF (E1 CAS) capable. As another example, FT_ROUTEABLE | FT_ISDN | FT_CAS | FT_R2MF indicates support for flexible routing plus all three front-end capabilities, including R2MF.

2.3.6. Getting, Using, and Closing Device Handles in a DM3 Flexible Routing Configuration

In the DM3 flexible routing configuration, R4 on DM3 works the same way as the R4 API. You can use the same GlobalCall device initialization, handling, and routing procedures for DM3 devices as you use for earlier-generation devices.

DM3 devices have similar characteristics to earlier-generation devices. The device must first be opened in order to obtain its handle, which can then be used to access the device functionality. Since an R4 for DM3 application must use GlobalCall for call control, i.e., for call setup and tear-down, all DM3 network interface devices must be opened with the gc_Open( ) or gc_OpenEx( ) function. However, if you need to open a network device and you aren't using call control (e.g., E1 clear channel configuration) or if you want to open a network board device for alarm handling, you can use dt_open( ).

Once the call has been established, voice and data streaming should be done using the Dialogic voice API. Functions such as dx_playiottdata( ), dx_reciottdata( ), and dx_dial( ) can be used. Of course, in order to do so, the voice device handle must be obtained. By the same token, in order to access the DTI routing functionality with functions such as dt_listen( ) and dt_unlisten( ), the corresponding DTI device handle must be obtained. The same thing applies to fax operations. A fax device must be explicitly opened using fx_open( ) so as to retrieve the fax device handle.

When opening a DM3 network interface device using gc_Open( ) or gc_OpenEx( ), the user has the option of also specifying a voice device in the devicename parameter. If a voice device is specified, then the network interface device is automatically associated with the voice device (it is attached and routed on the CT Bus). If a voice device is not specified, the voice device can be opened separately and then manually attached and routed to the network interface device.

NOTE:

DM3 voice devices can only be attached or specified in gc_OpenEx( ) or gc_Open( ) with DM3 network devices. You cannot attach or specify a DM3-SpringWare combination.

The following information applies to the DM3 flexible routing configuration and presents some additional guidelines for DM3 device-handling using the GlobalCall API.

• Use gc_Open( ) to open a network interface device. When opening a network interface device, a voice device may also be specified in the devicename parameter.
  • If a voice device is specified, it is automatically associated with the network interface device (it is attached and routed on the CT Bus). The gc_GetVoiceH( ) function can be used to retrieve the voice device handle and the gc_GetNetworkH( ) function can be used to retrieve the network interface device handle. In this case, the devicename string for the gc_Open( ) function is similar to the following:

		":N_dtiB1T1:V_dxxxB1C1:P_ISDN"

• If a voice device is not specified, the voice device must be opened separately using dx_open( ), and the device must be manually associated with the network interface device using the gc_Attach( ) function. In this case, the devicename string for the gc_Open( ) function is similar to the following:

		":N_dtiB1T1:P_ISDN"

See Section 5.3. gc_Open( ) and gc_OpenEx( ) Restrictions for more information.

• In general, when using DM3 and earlier-generation boards, the R4 for DM3 application must use a device-discovery procedure to become "hardware-aware." To perform device discovery and identify whether a logical device belongs to a DM3 board, use the SCbus routing device information functions, such as dx_getctinfo( ) and dt_getctinfo( ), and check the CT_DEVINFO ct_devfamily field for the CT_DFDM3 value. (For details see Section 3.3. CT_DEVINFO: Channel/Timeslot Device Information Data Structure and Section 11.3.2. Device Discovery for DM3 Boards and Earlier-Generation Boards.)
• For more detailed information on how to initialize GlobalCall for use with DM3 boards only, see Section 11.3.1. Initializing the GlobalCall API for DM3 Boards Only (Flexible Routing).
• To close the devices and release the device handles:
  • Use fx_close( ) to close any fax devices opened with fx_open( ).
  • Use gc_Detach( ) to detach any voice and network interface devices associated with gc_Attach( ).
  • Use dx_close( ) to close any voice devices opened with dx_open( ).
  • Use dt_close( ) to close any network interface devices opened with dt_open( ).
  • Use gc_Close( ) to close any voice and/or network interface devices opened with gc_Open( ).
• Application performance may be a consideration when opening and closing devices with GlobalCall. If the application uses GlobalCall to dynamically open and close devices as needed, it can impact the application's performance. One way to avoid this is to open all DM3 devices during application initialization and keep them open for the duration of the application, closing them only at the end.
• Since the fax library does not support the use of a voice handle for fax commands, you cannot use the device handle from dx_open( ) to call fax API functions. You must use fx_open( ) to open a channel device for fax processing and use that fax device handle. Therefore, it is recommended that when using flexible routing on DM3 boards you do the following to retrieve and use the fax device handle.
  • Use dx_open( ) to open the voice channel device and retrieve the voice device handle.
  • Optional: To determine whether the channel device supports fax before you attempt to open the fax device, use dx_getfeaturelist( ) and specify the voice device handle. If the ft_fax field of the returned FEATURE_TABLE structure contains the bitmask "FT_SENDFAX_TXFILE_ASCII | FT_FAX | FT_VFX40 | FT_VFX40E | FT_VFX40E_PLUS", then this device supports fax.
    
    If this is a fax only channel, close this voice device handle, as it will no longer be used. For more information on dx_getfeaturelist( ), see section 2.3.5. Determining Channel Capabilities in Flexible Routing Configurations.
  • Use fx_open( ) on the voice channel device to open the associated fax device and retrieve the fax handle. The function will succeed if the channel device has fax capabilities; otherwise the function will fail.

Table 1. Example of Assigned Device Names and Numbers in Windows

Hardware	Resource Type	Device Type	Logical Device Names/Numbers
D/480SC-2T1	Voice	Board	dxxxB1 to dxxxB12
(BLT board ID 5)*		Channel	dxxxB1C1 to dxxxB1C4
		- - - - - - -	to
		Channel	dxxxB12C1 to dxxxB12C4
	DNI**	Board	dtiB1 to dtiB2
		Timeslot	dtiB1T1 to dtiB1T24***
		Timeslot	dtiB2T1 to dtiB2T24***
DM/V960-4T1	Voice	Board	dxxxB13 to dxxxB36
(logical board ID 1)*		Channel	dxxxB13C1 to dxxxB13C4
		- - - - - - -	to
		Channel	dxxxB36C1 to dxxxB36C4
	DNI**	Board	dtiB3 to dtiB6
		Timeslot	dtiB3T1 to dtiB3T24***
		Timeslot	dtiB4T1 to dtiB4T24***
		Timeslot	dtiB5T1 to dtiB5T24***
		Timeslot	dtiB6T1 to dtiB6T24***
*Note that all earlier-generation devices (e.g., DualSpan D/480SC-2T1) are assigned device numbers (e.g., dxxxB1) before all DM3 devices (e.g., QuadSpan DM/V960-4T1) in Windows. **Digital Network Interface ***T23 if using ISDN

Click here to contact Dialogic Customer Engineering