Digital Network Interface Software Reference1. Prepare the digital network interface board for installation using the appropriate hardware installation card (see Appendix D - Related

Digital Network InterfaceSoftware Referencefor Linux and Windows

Copyright © 1999-2003 Intel Corporation

05-1313-005

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL®

PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANYINTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT ASPROVIDED IN INTEL�S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTELASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS ORIMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTSINCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULARPURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OROTHER INTELLECTUAL PROPERTY RIGHT. Intel products are not intended for use in medical,life saving, or life sustaining applications.

Intel may make changes to specifications and product descriptions at any time, without notice.

This document as well as the software described in it is furnished under license and may only be usedor copied in accordance with the terms of the license. The information in this manual is furnished forinformational use only, is subject to change without notice, and should not be construed as acommitment by Intel Corporation. Intel Corporation assumes no responsibility or liability for anyerrors or inaccuracies that may appear in this document or any software that may be provided inassociation with this document. Except as permitted by such license, no part of this document may bereproduced, stored in a retrieval system, or transmitted in any form or by any means without expresswritten consent of Intel Corporation.

Copyright © 1999-2003 Intel Corporation.

AnyPoint, BoardWatch, BunnyPeople, CablePort, Celeron, Chips, CT Media, Dialogic, DM3,EtherExpress, ETOX, FlashFile, i386, i486, i960, iCOMP, InstantIP, Intel, Intel Centrino, IntelCentrino logo, Intel logo, Intel386, Intel486, Intel740, IntelDX2, IntelDX4, IntelSX2, IntelInBusiness, Intel Inside, Intel Inside logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, IntelSingleDriver, Intel SpeedStep, Intel StrataFlash, Intel TeamStation, Intel Xeon, Intel XScale, IPLink,Itanium, MCS, MMX, MMX logo, Optimizer logo, OverDrive, Paragon, PDCharm, Pentium, PentiumII Xeon, Pentium III Xeon, Performance at Your Command, RemoteExpress, SmartDie, Solutions960,Sound Mark, StorageExpress, The Computer Inside., The Journey Inside, TokenExpress, VoiceBrick,VTune, and Xircom are trademarks or registered trademarks of Intel Corporation or its subsidiaries inthe United States and other countries.*Other names and brands may be claimed as the property of others.

Publication Date: October, 2003

Intel Converged Communications, Inc.1515 Route 10Parsippany NJ 07054For Technical Support, visit the Intel Telecom Support Resources website:http://developer.intel.com/design/telecom/support/For Products and Services Information, visit the Intel Communications Systems Products website:http://www.intel.com/network/csp/For Sales Offices, visit the Intel Telecom Building Blocks Sales Offices page:http://www.intel.com/network/csp/sales/

iii

Table of Contents1. How To Use This Manual ............................................................................... 11.1. Getting Started with this Guide...................................................................... 11.2. Organization of this Guide ............................................................................. 22. General Description ........................................................................................ 32.1. Typical Applications ...................................................................................... 32.2. Compatibility.................................................................................................. 42.3. SCbus Overview ............................................................................................ 53. Digital Telephony Overview........................................................................... 73.1. T1 Digital Telephony ..................................................................................... 7

3.1.1. T1 Frame Format................................................................................... 73.1.2. T1 Synchronization ............................................................................... 93.1.3. T1 Signaling .......................................................................................... 9

3.2. E1 Digital Telephony ................................................................................... 103.2.1. E1 Frame Format................................................................................. 103.2.2. E1 Synchronization ............................................................................. 123.2.3. E1 Signaling ........................................................................................ 133.2.4. E1 National and International Bits ...................................................... 15

3.3. Digital Network Interface Hardware Implementation.................................. 163.3.1. SCbus Routing..................................................................................... 163.3.2. Loss of Synchronization Alarm Handling ........................................... 163.3.3. Digital Network Interface Hardware Alarm Indicators ....................... 19

4. Function Overview ........................................................................................ 214.1. Digital Network Interface Function Categories ........................................... 21

4.1.1. Alarm Functions .................................................................................. 224.1.2. Diagnostic Functions ........................................................................... 224.1.3. Extended Attribute Functions.............................................................. 224.1.4. Parameter Request Functions .............................................................. 234.1.5. Parameter Setting Functions................................................................ 234.1.6. Resource Management Functions........................................................ 244.1.7. Routing Functions ............................................................................... 244.1.8. Time Slot Audio Functions ................................................................. 254.1.9. Time Slot Signaling Functions ............................................................ 25

4.2. Error Handling ............................................................................................. 264.3. Include Files ................................................................................................. 29

Digital Network Interface Software Reference for Linux and Windows

iv

5. Function Reference ....................................................................................... 31ATDT_BDMODE( ) - returns the current mode of every time slot ..................... 32ATDT_BDSGBIT( ) - returns the current state of the transmit and receive ........ 35ATDT_DNLDVER( ) - returns the firmware version .......................................... 39ATDT_IDLEST( ) - returns the current idle state ................................................ 44ATDT_ROMVER( ) - returns the version of the EPROM .................................. 47ATDT_STATUS( ) - returns the current status.................................................... 52ATDT_TSMODE( ) - returns the current signaling mode ................................... 55ATDT_TSSGBIT( ) - retrieves the current state .................................................. 58dt_castmgmt( ) - manage the CAS DTI templates ............................................... 61dt_castdecode( ) - decode the CAS DTI reply or event message block ............... 74dt_castencode( ) - validate and encode the message ............................................ 76dt_close( ) - closes digital network interface devices .......................................... 78dt_dial( ) - allows the application to pulse dial .................................................... 80dt_getctinfo( ) - returns information about the digital network interface ............. 85dt_getevt( ) - blocks and returns control to the program ...................................... 89dt_getevtmsk( ) - retrieves the current event bitmask(s) ...................................... 93dt_getparm( ) - gets the current value .................................................................. 98dt_getxmitslot( ) - returns the SCbus time slot................................................... 105dt_listen( ) - connects the digital listen channel ................................................. 108dt_open( ) - opens a digital network interface device ........................................ 112dt_rundiag( ) - runs diagnostics ......................................................................... 115dt_setevtmsk( ) - enables and disables notification for events ........................... 120dt_setidle( ) - enables or disables transmission .................................................. 126dt_setparm( ) - changes the value of a DNI device parameter ........................... 129dt_setsigmod( ) - sets the type of signaling ........................................................ 132dt_settssig( ) - sets or clears the transmit ........................................................... 135dt_settssigsim( ) - simultaneous setting or clearing of transmit signaling bits ... 138dt_tstcom( ) - tests the ability of a digital network interface device .................. 141dt_tstdat( ) - performs a test ............................................................................... 145dt_unlisten( ) - disconnects the receive .............................................................. 149dt_xmitalrm( ) - starts and stops transmission of an alarm ................................ 152dt_xmitwink( ) - transmits wink signaling ......................................................... 1556. Application Guidelines................................................................................ 1596.1. Writing a Simple Application .................................................................... 159

6.1.1. General Guidelines ............................................................................ 1596.1.2. Initialization....................................................................................... 1626.1.3. Processing.......................................................................................... 1676.1.4. Terminating ....................................................................................... 172

Table of Contents

v

6.1.5. Compiling and Linking ..................................................................... 1746.1.6. Aborting ............................................................................................ 174

6.2. Adding Advanced Features ........................................................................ 1747. Digital Network Interface API for DM3 ................................................... 1777.1. Overview of Digital Network Interface API for DM3 ............................... 1777.2. Digital Network Interface API Function Restrictions ................................ 1777.3. Detecting Layer 1 Alarms .......................................................................... 178Appendix A - Standard Runtime Library ..................................................... 181Digital Network Interface Entries and Returns .................................................. 181Event Management Functions............................................................................ 182Standard Attribute Functions ............................................................................. 185PT Structure ....................................................................................................... 187Appendix B - Message Blocks ......................................................................... 189Command Message Blocks ................................................................................ 189Reply Message Blocks ....................................................................................... 204Unsolicited Events ............................................................................................. 211Appendix C - dticas.h Header File.................................................................. 213

Appendix D - Related Publications................................................................. 219

Glossary ............................................................................................................ 221

Index.................................................................................................................. 227


vi

vii

List of TablesTable 1. Error Types Defined in dtilib.h ............................................................. 27Table 2. ATDT_DNLDVER( ) Return Values ................................................... 41Table 3. ATDT_ROMVER( ) Return Values ..................................................... 49Table 4. Common Data Types............................................................................. 63Table 5. dt_getevtmsk( ) Return Values.............................................................. 94Table 6. dt_getparm( ) Parameters ...................................................................... 98Table 7. Recommended dt_setalrm( ) Settings ................................................. 163Table 8. List of Digital Network Interface API Functions Fully Supported ..... 178Table 9. Guide to Appendix A .......................................................................... 182Table 10. Digital Network Interface Inputs for Event Management Functions 183Table 11. Digital Network Interface Returns from Event Management

Functions ................................................................................................... 185Table 12. Standard Attribute Functions ............................................................ 186Table 13. DV_TPT Structure ............................................................................ 187


viii

ix

List of FiguresFigure 1. D4 Frame Format................................................................................... 8Figure 2. D4 Superframe Format .......................................................................... 9Figure 3. E1 Frame Format ................................................................................. 11Figure 4. E1 Multiframe Format ......................................................................... 11Figure 5. Individual Frame Synchronization....................................................... 12Figure 6. Multiframe Synchronization ................................................................ 13Figure 7. Channel Associated Signaling (CAS) Protocol ................................... 14Figure 8. E1 National and International Bits....................................................... 15Figure 9. T1 Alarm Conditions ........................................................................... 17Figure 10. E1 Loss of Synchronization Alarm Requirements............................. 19Figure 11. Firmware Version Number Format.................................................... 40Figure 12. EPROM Version Number Format ..................................................... 48Figure 13. Transition Timing, Receive ............................................................. 189Figure 14. Transition Timing, Transmit............................................................ 189Figure 15. Pulse Timing, Receive ..................................................................... 192Figure 16. Pulse Timing, Transmit.................................................................... 192Figure 17. Pulse Train Timing, Receive ........................................................... 195Figure 18. Pulse Train Timing, Transmit .......................................................... 195


x

1

1. How To Use This Manual

This guide is for users who have a digital network interface or voice and networkboard and related software installed on a host computer operating in a Linux orWindows environment.

For a list of the hardware products supported with this software, see the ReleaseGuide for your system release.

1.1. Getting Started with this Guide

The following steps explain the order in which a digital network interface boardand related software products should be installed, checked, and programmed.

1. Prepare the digital network interface board for installation using theappropriate hardware installation card (see Appendix D - RelatedPublications).

2. Install this release by following the procedure described in the SoftwareInstallation Guide (for Linux or Windows).

3. Install the digital network interface board(s) in your computer following theprocedures in the appropriate hardware installation card (see Appendix D -Related Publications).

4. Refer to this Digital Network Interface Software Reference, and the StandardRuntime Library API Library Reference and the Standard Runtime LibraryAPI Programming Guide to develop application programs.

To use software for other devices, refer to the appropriate software reference forspecific instructions (see Appendix D - Related Publications).


2

1.2. Organization of this Guide

This Digital Network Interface Software Reference contains an overview of thedigital telephony interface and a digital network interface library C functionreference. It is organized as follows:

Chapter 2 provides a brief description of the digital network interface library ofC functions, typical applications using the digital network interface products, andan overview of the SCbus.

Chapter 3 presents an overview of digital telephony interface hardwareimplementation in relation to basic T1 and E1 telephony practices.

Chapter 4 presents an overview of the digital network interface library functionsand includes a discussion of C function error handling.

Chapter 5 provides a detailed alphabetical reference to the digital networkinterface library functions, including programming examples for each function.

Chapter 6 provides guidelines for the design of digital network interfaceapplications.

Chapter 7 provides information on using the digital network interface API onDM3 boards.

Appendix A lists returns and defines associated with the Standard RuntimeLibrary (SRL) that are unique to digital network interface devices.

Appendix B outlines the various message blocks and templates used with thevarious digital network interface devices.

Appendix C gives an example of the dticas.h header file.

Appendix D lists related publications.

A Glossary and an Index follow the appendices.

3

2. General Description

The digital network interface library of C functions allow a programmer to designapplication programs that run on a host PC and work with one or more digitalnetwork interface boards. The provided functions control the digital networkinterface device on the SCbus and the Network external interface to networkcircuits that meet either the T1 or E1 telephony standard.

This release includes Standard Runtime Library (SRL) functions used in networkapplications to perform such tasks as event management. SRL functions fornetwork applications are documented in Appendix A - Standard Runtime Libraryof this guide. For a complete explanation of the SRL, see the Standard RuntimeLibrary documentation.

2.1. Typical Applications

The type of applications supported by your software is dependent on the physicalconfiguration of the host PC system. For instance, a program that will run with adigital network interface board and other devices arranged in terminateconfiguration allows your system to act as a standalone voice processing node.Applications for this configuration include:

• Central-office-based voice mail• Cellular messaging• Audiotex• Service bureaus

A program designed to run with multiple digital network interface boardsarranged in drop-and-insert configuration allows individual channels toterminate at a voice processing device, pass transparently to the network, or both.Applications for this configuration include all the terminate applications plus:

• Operator services such as billing automation , directory assistance , andintercept treatments

• Telemarketing• Agent automation• Direct dial-in (DDI) service


4

2.2. Compatibility

This section describes compatibility of the digital network interface software withIntel Dialogic hardware and existing applications based on the Digital Networkdriver.

Some functions in the digital network interface library of C functions may operatedifferently or not at all on a given digital network interface board type due todifferences in the board�s usage. This section explains these differences infunctionality.

• dt_dial( ) is supported by the D/240SC-T1, D/240SC-2T1, D/300SC-E1,D/300SC-2E1, D/480SC-2T1, and D/600SC-2E1 boards.

NOTE: To perform dialing you can instead use a Voice library functionsupported by your D/xxx voice boards. The function name isdx_dial( ).

• dt_open( ) opens time slots from 1 to 24 in T1 applications (D/240SC-T1boards) or 1 to 30 in E1 applications (D/300SC-E1 boards).

• dt_getctinfo( ) is used to return device information for an on-board digitalnetwork interface device time slot.

• dt_getxmitslot( ) returns the SCbus time slot number connected to thetransmit of a digital network time slot.

• dt_listen( ) is used to connect the receive of a digital network time slot to anSCbus time slot.

• dt_unlisten( ) is used to disconnect the receive of a digital network interfacedevice time slot from the SCbus.

• dt_setalrm( ) DTA_DROP parameter is not supported by E1 compatibledigital network interface board devices. For these devices, use onlyDTA_NONE or DTA_TERM.

• dt_setevtmsk( ) and dt_getevtmsk( ) functions include the DTG_PDIGEVTparameter and also include additional parameters and masks for E1 alarmhandling (D/300SC-E1 only) and for T1 alarm handling (D240/SC-T1 only).See the function descriptions in Chapter 5. Function Reference for moreinformation.

2. General Description

5

• dt_setsigmod( ) transparent signaling mode is not supported in SCbusconfigurations.

• dt_xmitalrm( ) function uses additional parameters for E1 alarmtransmission (D/300SC-E1 only).

The library also supports the MSI/SC and DCB/SC boards. Refer to thereferences listed in Appendix D - Related Publications of this guide for moreinformation about functions supported on these boards.

2.3. SCbus Overview

SCbus is the TDM (Time Division Multiplexed) bus connecting SCSA (SignalComputing System Architecture) voice, telephone network interface and othertechnology resource boards together.

SCbus boards are treated as board devices with on-board voice and/or telephonenetwork interface devices which are identified by a board and channel (time slotfor digital network channels) designation, such as a voice channel, analogchannel or digital channel.


6

7

3. Digital Telephony OverviewThis chapter provides a brief overview of T1 and E1 concepts and a descriptionof how Intel Dialogic hardware works in T1 and E1 environments.

NOTE: It is beyond the scope of this guide to explain all the details of T1 andE1 digital telephony. For more detailed information, refer to the relatedpublications listed in Appendix D - Related Publications.

3.1. T1 Digital Telephony

A T1 circuit is used to transfer digital information in a two-way, full duplexconnection at a speed of 1.544 megabits per second (Mbps). In a T1environment, this rate is known as digital signal level 1 or DS-1. A T1 circuitcontains 24 voice channels, each operating at a rate of 64,000 bits per second(bps), a rate known as digital signal level 0 or DS-0. The formula used tocalculate the DS-1 rate of 1.544 Mbps includes an extra 8,000 bits that are notpart of the voice data but used to synchronize the data received and transmittedon the T1 circuit.

64,000 bps (Voice Channel Rate, DS-0) x 24 (Number of Voice Channels)

1,536,000 bps + 8,000 (Controlling Bits)

1,544,000 (T1 Circuit Rate, DS-1)

The T1 compatible digital network interface boards de-multiplex the 24 voicechannels on a T1 circuit and pass them on to associated hardware (such as a voiceboard or other resource sharing module).

3.1.1. T1 Frame Format

Digital data on a T1 line is organized into D4 frames. A D4 frame consists of asingle 8-bit sample from each of the 24 voice channels and one framing bit, for atotal of 193 bits. Each 8-bit sample occupies what is known as a time slot withinthe frame. Figure 1 shows one D4 frame.


8

ON

OFF

FramingBit

Timeslot 1

Bits1 2 3 4 5 6 7 8

Timeslot 24

Bits1 2 3 4 5 6 7 8

193 Bits

Figure 1. D4 Frame Format

The term time slot is derived from the method that is used to multiplex the 24voice channels in a D4 frame. The channels are byte-interleaved in a frame. Thatis, each byte is a sample from a different voice channel and occurs in a fixedpattern within the frame (voice channel one in time slot one, voice channel two intime slot two, etc.). All D4 frames have the same pattern. This technique ofinterleaving is called time division multiplexing.

Twelve D4 frames make up what is known as a D4 superframe. Figure 2 shows asingle D4 superframe, indicating the framing bit values of the individual D4frames. The framing bits are used for frame synchronization, which is describedin more detail in Section 3.1.2. T1 Synchronization.

3. Digital Telephony Overview

9

1 1 1 1 1

Framing Bit

1 0 00000

D4 Frame (24 Timeslots)

D4 Superframe (12 D4 Frames)

Figure 2. D4 Superframe Format

3.1.2. T1 Synchronization

To identify DS-0 voice channels for the receiver, the data being transferred mustbe synchronized. This capability is built into the D4 frame and superframeformats for T1 systems. Each D4 frame in a superframe begins with a framingbit. The 12 framing bits in a D4 superframe are arranged in a predefined pattern:100011011100. By searching for this pattern, the T1 compatible digital networkinterface hardware can determine the beginning and end of every D4 superframe,D4 frame, and time slot. When this pattern cannot be found, the resulting error isknown as Receive Loss of Synchronization (RLOS). See Section 3.3.2. Loss ofSynchronization Alarm Handling for information on T1 alarm handling.

3.1.3. T1 Signaling

T1 signaling information (on-hook and off-hook states) must be carried on a T1line. Signaling is accomplished using two bits called the A-bit and the B-bit.Each time slot in the sixth frame of the D4 superframe has the least significant bitreplaced with signaling information. These are the A-bits. Similarly, each timeslot in the 12th frame of the D4 superframe has the least significant bit replacedwith signaling information. These are the B-bits. This strategy of replacing theleast significant bit with signaling information is called robbed-bit signaling.


10

For example, in E&M (Ear and Mouth) protocol the signaling bits indicatewhether the sending party�s line is on-hook or off-hook. When the signaling bitsare 0s, the line is on-hook, and when the signaling bits are 1s, the line is off-hook.

NOTE: Some T1 services reverse these values or use them in different patternsor protocols. Check with your T1 supplier to verify the A-bit and B-bitvalues for your T1 service.

3.2. E1 Digital Telephony

An E1 circuit is a digital two-way connection operating at a speed of 2.048 Mbps.This rate is achieved by combining 32 time slots operating at a rate of 64 Kbps.

64,000 bps (Individual Voice Channel Rate) x 32 (Number of Channels or Time Slots)

2,048,000 (E1 Circuit Rate)

These 32 time slots include 30 time slots available for up to 30 voice channels,one time slot dedicated to carrying frame synchronization information (time slot0), and one time slot dedicated to carrying signaling information (time slot 16).The E1 compatible digital network interface boards de-multiplex the 30 voicechannels and pass them on to E1 compatible resource modules.

NOTE: E1 is used to refer to the 2.048 Mbps Digital Service with ChannelAssociated Signaling (CAS). This service is available in Europe andsome parts of Asia.

3.2.1. E1 Frame Format

On an E1 circuit, data is organized into frames on a byte-interleaved basis. Datais taken from each voice channel a byte at a time. The resulting E1 framecontains 32 time slots: one to carry frame synchronization information, one tocarry signaling information, and 30 to carry voice channel data. Each time slotcontains 8 bits, for a total of 256 bits per frame. Figure 3 illustrates the structureof an E1 frame.


11

Timeslot 1

Bits1 2 3 4 5 6 7 8

Timeslot 31

Bits1 2 3 4 5 6 7 8

256 Bits

Figure 3. E1 Frame Format

E1 frame format numbers time slots from 0 to 31.

E1 frames 0 through 15 are combined into one multiframe. Figure 4 illustratesthe structure of an E1 multiframe.

FRAME 0 FRAME 1 FRAME 14 FRAME 15

4096 Bits

Figure 4. E1 Multiframe Format


12

3.2.2. E1 Synchronization

Time slot 0 of each frame (frames 0 through 15 of a multiframe) carries theinformation needed to identify voice channels for the receiver on E1 systems.The pattern carried by time slot 0 alternates between two patterns: the first is a 7-bit pattern (0011011) in bit positions 6 through 0 and the second is a pattern ofnational and international bits with a single 1-bit in bit position 6. Figure 5shows the alternating bit patterns in odd and even frames.

Time Slot 0 of Each Frame

Bit Position

I

I

0 0 1 1 0 1 1

1 - N N N N N

7 6 5 4 3 2 1 0MSB LSB

Odd Frame

Even Frame

I - International BitN - National Bit

MSB - Most Significant BitLSB - Least Significant Bit

Figure 5. Individual Frame Synchronization

See Section 3.2.4. E1 National and International Bits for an explanation of theE1 national and international bits pictured in Figure 5.

Frame 0 (the first frame within an E1 multiframe) contains additionalsynchronization information to identify the beginning of a multiframe. Thebeginning is identified by a pattern of four zeros in bit positions 7 through 4 oftime slot 16, frame 0. Figure 6 illustrates the bit pattern found in time slot 16 offrame 0.


13

Time Slot 16 of Frame 0

Bit Position

0 0 0 0 X Y X X

7 6 5 4 3 2 1 0MSB LSB

X - Extra Bits, Used for Multi-frame SynchronizationY - Distant Multi-frame Alarm Bit

Figure 6. Multiframe Synchronization

If these frame or multiframe bit patterns cannot be found, the resulting error isknown as a Frame Sync Error (FSERR) or Multiframe Sync Error (MFSERR). Ifeither an FSERR or MFSERR error is detected, a remote alarm or a distant multi-frame alarm is sent to the remote end. The condition exists until synchronizationis recovered. See Section 3.3.2. Loss of Synchronization Alarm Handling forinformation on E1 alarm handling.

3.2.3. E1 Signaling

The Conference of European Postal and Telecommunications administrations(CEPT) defines how bits of a PCM carrier system in E1 areas will be used and inwhat sequence. E1 circuits use the Channel Associated Signaling (CAS)protocol. Frames using CAS share time slot 16, which carries signalinginformation for two time slots or voice channels at a time.

Time slot 16 contains two groups of four bits, known as nibbles, that aredesignated the upper nibble and the lower nibble. Two channels send theirsignaling bits in each frame � one using the upper nibble, the other using thelower nibble. As explained in Section 3.2.1. E1 Frame Format on E1 frameformat, it takes 15 frames to carry signaling information for each of the 30 voicechannels.

Time slot 16 of frame 0 carries a special pattern. The upper nibble carries apattern of four 0s, which identifies the frame as frame 0 of an E1 multiframe.


14

The lower nibble of time slot 16 in frame 0 carries a pattern of extra bits and analarm bit. The X bits pictured in Figure 7 are the extra bits used for multiframesynchronization (see Section 3.2.2. E1 Synchronization). The Y bit pictured inFigure 7 is the distant multiframe alarm bit (see Section 3.3.2. Loss ofSynchronization Alarm Handling).

Time slot 16 of frame 1 in an E1 multiframe carries signaling information for thefirst and 16th channels. Time slot 16 of frame 2 in an E1 multiframe carriessignaling information for the 2nd and the 17th channels. This continues untilframe 15 which carries signaling information for the 15th and 30th channels.

MSB LSB

Time Slot 16

Voice Channel 1 Voice Channel 16


Voice Channel N Voice Channel N + 15


0 0 0 0 0 0 0 0

D C B A

3 2 1 07 6 5 4

D C B A(Upper Nibble) (Lower Nibble)

Frame 0:

Frame 1:

Frame 2:

Frame N:

Frame 15:

Figure 7. Channel Associated Signaling (CAS) Protocol

CautionDo not set signaling bits ABCD to 0000. As explained in Section

3.2.2. E1 Synchronization on E1 synchronization, this setting is used toidentify frame 0 of an E1 multiframe.


15

Clear Channel TS16 Feature

The Clear Channel TS16 feature allows the use of time slot 16 for data on E1interface boards. This feature is enabled or disabled by adding one of thefollowing lines to /usr/dialogic/cfg/dialogic.cfg:

FEATURES = TS16_CLEAR

This command selects Clear Channel Time Slot 16 (CCTS16) for E1 interfaceboards, ignores E1 signaling received from the network on time slot 16, andtransmits FFH. Access to time slot 16 is not available.

FEATURES = TS16_SIG

This command specifies that the E1 interface board will use the default of E1signaling on time slot 16.

3.2.4. E1 National and International Bits

National and international bits are set in time slot 0. The most significant bit (bitposition 7) in time slot 0 of each frame contains the international bit. Thenational bits occupy bit positions 0 through 4 of time slot 0 of every secondframe. Figure 8 shows national and international bit settings.

TIMESLOT0

BITPOSITION

ODD FRAME

EVEN FRAME

LI - INTERNATIONA BIT N - NATIONALBIT

7 6 5 4 3 2 1 0

I 0 0 1 1 0 1 1

I 1 N N N N N

Figure 8. E1 National and International Bits


16

3.3. Digital Network Interface Hardware Implementation

The following sections describe features of the digital network interface hardwareimplementation that are important to note for purposes of applicationdevelopment.

3.3.1. SCbus Routing

Data is transmitted over the SCbus in 1024 time slots. At system initiation anddownload, the number of devices (analog interface, voice, digital networkinterface, facsimile, etc.) on each board and the number of SCbus time slotsrequired to service these devices are determined. Only one digital networkinterface device time slot can transmit on a specific SCbus time slot at a time. Toassure this, the transmit of all devices are assigned to a specific and unique SCbustime slot at system initialization. This transmit assignment cannot be changed bythe application.

When both voice and telephone network digital interface devices (T1/E1) are on asingle SCbus board, these resources are treated as separate and independentdevices.

3.3.2. Loss of Synchronization Alarm Handling

The most critical error condition that can occur on a T1 or E1 line is ReceiveLoss of Synchronization (RLOS). This section describes the alarm conditionsand signals associated with digital network interface alarm handling and how theyare indicated on a digital network interface board.

T1 Alarm Handling

For T1 applications, the T1 compatible digital network interface boards generatethree alarm conditions to indicate RLOS:

• Red alarm• Yellow alarm• Blue alarm


17

A red alarm condition occurs when RLOS has existed for 2.5 seconds (default)on incoming data. This condition will exist until the synchronization has beenrecovered and remains recovered for 12 seconds (default).

A yellow alarm is sent by the receiving T1 digital network interface device to thetransmitter device. The yellow alarm indicates to the transmitter device that a redalarm condition exists at the receiver device. The yellow alarm is sent for as longas the red alarm condition exists at the receiver device.

NOTE: A yellow alarm is sent by the T1 digital network interface receiverdevice by inserting a zero in bit 2 of all time slots.

The blue alarm is a �keep alive� signal. When the T1 digital network interfacedevice is used in a drop and insert configuration and it receives an RLOS for2.5 seconds, a red alarm condition is entered on the T1 digital network interfaceside that received the RLOS. The configuration then transmits a blue alarmsignal from the other digital network interface connected via the SCbus cable toits T1 span. The blue alarm signal informs the receiving station that there is aproblem on the line and allows the receiving station to continue to derive itstransmit clock from the received signal.

NOTE: The blue alarm signal causes an RLOS on the T1 digital networkinterface device that receives the blue signal. A blue alarm consists ofan unframed pattern of 1s.

DTI/241 DTI/241TransmittingNetwork

DownstreamNetwork

Yellow alarm transmittedto network

Blue alarm transmittedto downstream device

Figure 9. T1 Alarm Conditions


18

E1 Alarm Handling

For E1 applications, the E1 compatible digital network interface boards generatefour alarm conditions to indicate loss of synchronization (FSERR or MFSERR):

• Remote alarm• Unframed all 1s alarm• Distant multiframe alarm• Signaling all 1s alarm

A remote alarm is generated by the E1 compatible digital network interfacedevice to indicate it has detected a loss of frame synchronization on the receiveline (FSERR condition). The remote alarm is transmitted to the E1 network. Aremote alarm is returned to the network by setting bit 3 of time slot 0 in non-alignment frames to 1. (�Non-alignment frames� are those frames not carryingthe 7-bit frame-sync pattern 0011011 in time slot 0.)

If the E1 compatible digital network interface device is in a drop-and-insertconfiguration, it also generates an unframed all 1s alarm. The unframed all 1salarm is transmitted to the downstream device to indicate that the data it isreceiving is unsynchronized at the frame level and is therefore unreliable. Thedownstream device must then transmit this alarm to the downstream network.

When the E1 compatible digital network interface device detects a recovery offrame synchronization, it will stop transmitting the remote and unframed all 1salarms.

A distant multiframe alarm is generated by the E1 compatible digital networkinterface device to indicate it has detected a loss of multiframe synchronizationon the receive line (MSFERR condition). The distant multiframe alarm istransmitted to the E1 network. The digital network interface device returns adistant multiframe alarm by setting the bit in position 2 of time slot 16 in frame 0to 1.

If the E1 compatible digital network interface device is in a drop-and-insertconfiguration, it also generates a signaling all 1s alarm. A signaling all 1s alarmis generated by inserting all 1s in time slot 16. The signaling all 1s alarm istransmitted to the downstream device to indicate that the data it is receiving is


19

unsynchronized at the multiframe level and is therefore unreliable. Thedownstream device must then transmit this alarm to the downstream network.

When the E1 compatible digital network interface device detects a recovery ofmultiframe synchronization, it will stop transmitting the distant multiframe andsignaling all 1s alarms.

DTI/241 DTI/241TransmittingNetwork

DownstreamNetwork(or PBX)

DTI/241 detects loss of frame synchon the upstream receive line:

Remote Alarm transmittedto the upstream network

DTI/241 detects loss of multi-framesynch on the upstream receive line:

Distant multi-frame alarmtransmitted to the upstream network

Unframed all 1s alarm transmittedto the downstream network

Signaling all 1s alarm transmittedto the downstream network

Any DTI/241 device receiving one ofthese alarms must transmit the givenalarm to the downstream network.

Figure 10. E1 Loss of Synchronization Alarm Requirements

3.3.3. Digital Network Interface Hardware Alarm Indicators

The three LEDs on the rear bracket of the digital network interface board indicatethe state of the signal being received. All LED indicators will remain lit until thedigital network interface firmware is downloaded to the device.

Red LED: The red LED lights up whenever the digital network interface devicedetects RLOS.


20

Yellow LED: A yellow LED lights up whenever the digital network interfacedevice receives an alarm indicating that a network span is receivingunsynchronized data from the digital network interface board.

Green LED: A green LED is lit whenever the digital network interface board isreceiving a signal.

NOTES: 1. Red, yellow, and green LEDs will be lit when the system is poweredup, regardless of whether or not a signal is being received.

2. No alarm handling is performed until digital network interfaceboards are downloaded.

3. Once the firmware is downloaded, the default alarm handling modefor digital network interface boards is terminate alarm handling [seedt_setalrm( )].

21

4. Function OverviewThis chapter describes the digital network interface library functions that controlthe digital network interface hardware. A complete reference describing thesefunctions in detail is located in Chapter 5. Function Reference.

4.1. Digital Network Interface Function Categories

The digital network interface library functions provide the necessary buildingblocks to create voice applications using T1 or E1 lines. These functions can bedivided into the following categories:

• Alarm functions - control T1 or E1 alarm handling• Diagnostic functions - test digital network interface hardware• Extended Attribute functions - retrieve device-specific attribute data• Parameter Request functions - request device parameters• Parameter Setting functions - set device parameters• Resource Management functions - open and close digital network interface

devices• Routing functions - generate communication between devices connected to

time slots• Time Slot Audio functions - generate audio signals on time slots• Time Slot Signaling functions - alter signaling portion of time slot

For digital network interface library support on DM3 boards, see Chapter7. Digital Network Interface API for DM3.

NOTE: Many digital network interface library functions can operate in eithersynchronous mode or asynchronous mode. Synchronous functions donot return control to the calling process until the function call iscompleted. To operate a function in asynchronous mode, yourapplication must include an event handler to trap and process thecompletion event.


22

Each category and its functions are briefly described in the following sections.

4.1.1. Alarm Functions

• dt_setalrm( ) - set alarm handling mode• dt_xmitalrm( ) - start/stop alarm transmission

The Alarm functions allow your application to control the way T1 or E1 alarmsare handled. The dt_setalrm( ) function sets the alarm-handling mode. Thedt_xmitalrm( ) function starts and stops the transmission of alarms.

For a detailed discussion of T1 and E1 alarm handling, refer to Chapter3. Digital Telephony Overview.

4.1.2. Diagnostic Functions

• dt_rundiag( ) - run diagnostics on Network firmware• dt_tstcom( ) - test board Interface communications• dt_tstdat( ) - run data test on board device

The Diagnostic functions check the Network firmware and hardware. Thedt_rundiag( ) function runs diagnostics on the Network firmware and the othertwo functions test the hardware. The dt_tstcom( ) function tests communicationbetween the PC and the digital network interface device. The dt_tstdat( )function tests the reliability of data transfer between the PC and the digitalnetwork interface device.

4.1.3. Extended Attribute Functions

• ATDT_BDMODE( ) - board signaling mode (all time slots)• ATDT_BDSGBIT( ) - board signaling bits (all time slots)• ATDT_DNLDVER( ) - downloaded Network firmware version• ATDT_IDLEST( ) - time slot idling state• ATDT_ROMVER( ) - EPROM version• ATDT_STATUS( ) - time slot status• ATDT_TSMODE( ) - get time slot signaling mode• ATDT_TSSGBIT( ) - get time slot signaling bits

4. Function Overview

23

Standard Attribute functions, which are contained in the Standard RuntimeLibrary (SRL, see Appendix A - Standard Runtime Library), provide genericinformation about a device, such as its name or the status of the last function callof the device. Extended Attribute functions return device specific information.The digital network interface library Extended Attribute functions returninformation about digital network interface logical board and time slot devices.

Extended Attribute function error handling is similar to that of other digitalnetwork interface library functions. Most Extended Attribute functions returnAT_FAILURE on error. One Extended Attribute function, ATDT_BDSGBIT( ),returns the value AT_FAILUREP on error. Refer to Section 4.2. Error Handlingfor information about retrieving errors.

4.1.4. Parameter Request Functions

• dt_getparm( ) - get device parameter• dt_getevt( ) - blocks and returns control after event• dt_getevtmsk( ) - get device event bitmask

Parameter Request functions are used to check the status of Network parameterand event mask settings.

4.1.5. Parameter Setting Functions

• dt_setparm( ) - change device parameter• dt_setevtmsk( ) - change device event mask

The Parameter Setting functions set Network device parameters and masks usedfor event management.


24

4.1.6. Resource Management Functions

• dt_open( ) - open board or time slot device• dt_close( ) - close board or time slot device

Resource Management functions open and close devices. Before you canperform an operation on a device, the device must be opened. The dt_open( )function returns a unique device handle. All subsequent operations on the devicemust use this handle.

NOTES: 1. A device handle is NOT the same as a system file handle.

2. Opening or closing a digital network interface device does not affectother processes using the device. (See Chapter 6. ApplicationGuidelines, for more information on opening and using DTIdevices.)

3. The value returned by dt_open( ) for a digital network interfacelogical board is referred to as a logical board device handle in thisguide.

4.1.7. Routing Functions

Refer to the SCbus Routing Function Reference for more information about thesefunctions.

• dt_getctinfo( ) - get information about the digital network interface time slotdevice connected to the SCbus

• dt_getxmitslot( ) - returns SCbus time slot connected to the digital networkinterface time slot device

• dt_listen( ) - connects the receive of a digital network interface time slotdevice to an SCbus time slot

• dt_unlisten( ) - disconnects the receive of a digital network interface timeslot device from an SCbus time slot

Routing functions enable the application to make or break a connection betweenvoice, telephone network interface and other resource channels connected viaSCbus time slots.


25

4.1.8. Time Slot Audio Functions

• dt_setidle( ) - enable/disable time slot idle state

A Time Slot Audio function affects only the transmitted audio portion of a timeslot. It replaces the normal voice data on the audio portion of a time slot withother data. The dt_setidle( ) function transmits an idle pattern (digital equivalentof silence) on the selected digital network interface time slot. The specific idlepattern transmitted can be specified via the download configuration file or byusing the dt_setparm( ) function.

4.1.9. Time Slot Signaling Functions

• dt_dial( ) - dial a pulse digit string• dt_setsigmod( ) - change time slot transmit signaling mode• dt_settssig( ) - change time slot signaling bits• dt_settssigsim( ) - clear and set signaling bits simultaneously• dt_xmitwink( ) - transmit wink signaling

Time Slot Signaling functions affect the transmitted signaling portion of a timeslot. The dt_setsigmod( ) function selects the origin of the signaling information.The signaling information can either be inserted by the digital network interfacehardware or derived (by way of the SCbus) from an SCbus compatible resourcedevice (such as a D/240SC-T1) or another network device. The dt_settssig( )function sets the state of the signaling bits when the signaling information isinserted by the digital network interface board (signaling insertion mode). Thedt_xmitwink( ) function transmits wink signaling to the network on any of theavailable signaling bits (for T1, bit A or B; for E1, bit A, B, C, or D).

NOTES: 1. The signaling bit and polarity used for wink signaling are onlyconfigurable through the download parameter file. See the SoftwareInstallation Guide (for Linux or Windows) for details.

2. If your configuration includes Voice boards, you can use the Voicelibrary function dx_dial( ) instead.


26

4.2. Error Handling

All digital network interface library functions return a value that indicates thesuccess or failure of the function call. Generally, digital network interface libraryfunctions return the following values:

• 0 - function success• -1 - general error• AT_FAILURE - Extended Attribute function error from a function that

returns a value• AT_FAILUREP - Extended Attribute function error from a function that

returns a pointer

If a function fails, the error code can be retrieved using the Standard RuntimeLibrary (SRL) ATDV_LASTERR( ) function. The error codes are defined indtilib.h and listed in Table 1.

NOTES: 1. The Network dt_open( ) function call returns a device handle if thefunction call is successful. A device handle is a positive non-zerovalue. If dt_open( ) fails, the return code is -1 and the specific erroris a system error which can be found in the global variable errno,contained in errno.h.

2. The ATDT_BDSGBIT( ) function call returns the valueAT_FAILUREP on error. All other Extended Attribute functionsreturn AT_FAILURE on error.

3. The SRL Standard Attribute functions ATDV_LASTERR( ) andATDV_ERRMSGP( ) can be used to obtain the status of the lastfunction call of the device. Refer to Appendix A - Standard RuntimeLibrary for more information.

4. If the error returned by ATDV_LASTERR( ) is EDT_SYSTEM, asystem error has occurred. Check the value of the global variableerrno defined in errno.h.


27

Table 1. Error Types Defined in dtilib.h

Error Returned Description

EDT_ABORT abort received responseEDT_ADDRS bad addressEDT_BADCMDERR invalid or undefined command to driverEDT_BADCNT count of bytes requested is badEDT_BADDEV bad device errorEDT_BADGLOB bad global (device) parameter numberEDT_BADPORT 1st byte appeared on reserved portEDT_BADVAL invalid parameter value passed in value

pointerEDT_BITBSY bit is already setEDT_CHKSUM bad checksumEDT_DATTO data reception timed outEDT_DTTSTMOD in test mode; cannot set DTI/2xx modeEDT_FWERR firmware returned an errorEDT_INVBD invalid DTI/2xx logical board device

handleEDT_INVCFG invalid configuration area or EEPROM

configuration dataEDT_INVMSG invalid messageEDT_INVSIGST invalid signaling stateEDT_MBFMT wrong number of bytes for multiple byte

requestEDT_MBIMM received an immediate terminationEDT_MBINV 1st byte appeared on data portEDT_MBOVR message was too long, overflowEDT_MBPORT received multiple byte data on port other

than 0 or 1EDT_MBTERM terminating byte other than FEH or FFH


28


EDT_MBUND under the number of bytes for a multibyterequest

EDT_MSGCNT count received did not match actual countEDT_MTSIG cannot disable insertionEDT_NOIDLEERR time slot is not in idle/closed stateEDT_NOMEMERR cannot map or allocate memory in driverEDT_NOTDNLD not downloadedEDT_NOTSACS cannot use tsacs on the deviceEDT_NOWTCALL not waiting for a callEDT_PARAMERR invalid parameterEDT_PDOFFHK wink bit not in correct initial stateEDT_PDSIG cannot disable insertionEDT_RANGEERR bad/overlapping physical memory rangeEDT_SH_BADEXTTS external time slot unsupported at current

clock rateEDT_SH_BADINDX invalid switching handler index numberEDT_SH_BADLCLTS invalid local time slot numberEDT_SH_BADMODE invalid bus modeEDT_SH_BADTYPE invalid local time slot typeEDT_SH_LCLDSCNCT local time slot already disconnected from

SCbusEDT_SH_LCLTSCNCT local time slot already connected to SCbusEDT_SH_LIBBSY switching handler library is busyEDT_SH_LIBNOTINIT switching handler library has not been

initializedEDT_SH_MISSING switching handler is not presentEDT_SH_NOCLK clock fallback failedEDT_SIGINS signaling insertion not enabledEDT_SIGTO transmit/receive did not update in timeEDT_SIZEERR message too big or too small


29


EDT_SKIPRPLYERR a required reply was skippedEDT_STARTED cannot start when already startedEDT_SUCC no errorEDT_SYSTEM System error - check the global variable

errno for more information about theerror.

EDT_TMOERR timed out waiting for reply from firmwareEDT_TSASN time slot already assignedEDT_TSBSY time slot is busy

4.3. Include Files

The digital network interface library function prototypes and defines are listed inthe dtilib.h file supplied with this release. Applications that use these libraryfunctions must include the following statements:

#include <windows.h> /* For Windows applications only */ #include <srllib.h> #include <dtilib.h>

To perform error handling in your routines, your source code must include thefollowing line:

#include <errno.h>

Code that uses Voice devices and Voice Driver with digital network interfacedevices must include the following statements, in the following order:

#include <windows.h> /* For Windows applications only */ #include <srllib.h> #include <dxxxlib.h> #include <dtilib.h> #include <errno.h>


30

31

5. Function Reference

This chapter contains an alphabetical listing of all digital network interfacelibrary functions. Extended Attribute functions, also contained in the digitalnetwork interface library, are described here as well (because the functionsappear alphabetically, the Extended Attribute functions are located together nearthe front of the reference). For information about Standard Attribute functions,refer to Appendix A - Standard Runtime Library.

For digital network interface library support on DM3 boards, see Chapter7. Digital Network Interface API for DM3.

NOTE: Unless otherwise noted, all functions listed in this section apply to bothLinux and Windows operating systems.

ATDT_BDMODE( ) returns the current mode of every time slot

32

Name: long ATDT_BDMODE(devh)Inputs: int devh • digital network interface

logical board device handle Returns: signaling mode of all digital network interface time slots

AT_FAILURE if failure Includes: srllib.h

dtilib.h Category: Extended Attribute

Mode: synchronous

! Description

The ATDT_BDMODE( ) function returns the current mode of every time slot onthe specified digital network interface device.

Parameter Description

devh: Specifies the valid digital network interface logical boarddevice handle returned by a call to dt_open( )

For T1 applications, the mode is returned as a long integer where bits 0 to 23represent the mode of digital network interface time slots 1 to 24.

For E1 applications, the mode is returned as a long integer where bits 0 to 29represent the mode of digital network interface time slots 1 to 30.

The following signaling mode defines are provided in dtilib.h:

• DTM_SIGINS - signaling insertion mode (digital network interface boardgenerates signaling to network)

To determine the mode of a time slot, compare the returned value with theprovided defines.

returns the current mode of every time slot ATDT_BDMODE( )

33

! Cautions1. This function will fail if an invalid digital network interface logical board

device handle is specified.

2. For returned values to be valid, you must call dt_setsigmod( ) first

3. Wink signaling cannot be transmitted on a voice device channel (see theVoice API Library Reference and the Voice API Programming Guide).

! Example

#include <windows.h> /* For Windows applications only */ #include <srllib.h> #include <dtilib.h> #include <errno.h>

main() { int devh; /* Board device handle */ long modebits; /* Mode of all time slots */ int i; /* Loop counter */ /* * Open board 1 device */ if ( ( devh = dt_open( "dtiB1", 0 ) ) == -1 ) { printf( "Cannot open board dtiB1. errno = %d", errno ); exit( 1 ); } /* * Get the signaling mode of all E-1 time slots (1 to 30) */

if ( ( modebits = ATDT_BDMODE( devh ) ) == AT_FAILURE ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } /* * Display it */ for ( i = 0; i < 30; i++ ) { switch( ( modebits >> i ) & 1 ) { case DTM_TRANSP: printf( "Time slot %d on board 1 is in transparent mode\n", i + 1 ); break; case DTM_SIGINS: printf( "Time slot %d on board 1 is in insertion mode\n", i + 1 ); break; } } . . }

ATDT_BDMODE( ) returns the current mode of every time slot

34

! Errors

If the function returns AT_FAILURE, use the SRL Standard Attribute functionATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) toobtain a descriptive error message. See Appendix A - Standard Runtime Libraryfor more information on SRL functions. The error codes returned byATDV_LASTERR( ) are:

• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid command parameter to driver• EDT_INVBD - invalid digital network interface logical board device handle• EDT_INVMSG - invalid message• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_RANGERR - bad/overlapping physical memory range• EDT_SIZEERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - System error. Check the global variable errno for more

information about the error.• EDT_TMOERR - timed out waiting for reply from firmware

Error defines can be found in the file dtilib.h.

! See Also• ATDT_BDSGBIT( )• ATDT_TSMODE( )• ATDT_TSSGBIT( )• dt_setsigmod( )• dt_settssig( )

returns the current state of the transmit and receive ATDT_BDSGBIT( )

35

Name: char * ATDT_BDSGBIT(devh) Inputs: int devh • digital network interface

logical board device handle Returns: pointer to signaling bit states of all device time slots

AT_FAILUREP if failure Includes: srllib.h


Mode: synchronous

! Description

The ATDT_BDSGBIT( ) function returns the current state of the transmit andreceive bits for all time slots on the digital network interface device specified indevh.



For T1 applications, the returned value is a pointer to a 24-byte buffer. Bytes 0 to23 represent T1 time slots 1 to 24.

For E1 applications, the returned value is a pointer to a 30-byte buffer. Bytes 0 to29 represent E1 time slots 1 to 30.

ATDT_BDSGBIT( ) returns the current state of the transmit and receive

36

The following symbols represent each signaling bit and are defined in dtilib.h:

• DTSG_RCVA - �A� receive signaling bit• DTSG_RCVB - �B� receive signaling bit• DTSG_RCVC - �C� receive signaling bit (E1 only)• DTSG_RCVD - �D� receive signaling bit (E1 only)• DTSG_XMTA - �A� transmit signaling bit• DTSG_XMTB - �B� transmit signaling bit• DTSG_XMTC - �C� transmit signaling bit (E1 only)• DTSG_XMTD - �D� transmit signaling bit (E1 only)

To determine the state of the signaling bits, perform a logical AND operation onthe byte buffer and the defines, as demonstrated in the example below.

! Cautions1. This function will fail if an invalid digital network interface logical board

device handle is specified. AT_FAILUREP will be returned.

2. The transmit signaling bits are only valid when the device is in signalinginsertion mode.

returns the current state of the transmit and receive ATDT_BDSGBIT( )

37

! Example


main() { int devh; /* Board device handle */ char *sigbits; /* Pointer to signaling bits array */ int i; /* Loop counter */ int arcv, brcv, axmt, bxmt; /* Bit mask values */

/* * Open board 1 device */ if ( ( devh = dt_open( "dtiB1", 0 ) ) == -1 ) { printf( "Cannot open board dtiB1. errno = %d", errno ); exit( 1 ); }

/* * Get current transmit and receive signaling bits of all time slots */ if ( ( sigbits = ATDT_BDSGBIT( devh ) ) == AT_FAILUREP ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); }

/* * Display it */ for ( i = 0; i < 24; i++ ) { arcv = ( sigbits[ i ] & DTSG_RCVA ) ? 1 : 0; brcv = ( sigbits[ i ] & DTSG_RCVB ) ? 1 : 0; axmt = ( sigbits[ i ] & DTSG_XMTA ) ? 1 : 0; bxmt = ( sigbits[ i ] & DTSG_XMTB ) ? 1 : 0; printf( "tslot #%d arcv = %d, brcv = %d, axmt = %d, bxmt = %d\n", i + 1, arcv, brcv, axmt, bxmt ); } . . . }

ATDT_BDSGBIT( ) returns the current state of the transmit and receive

38

! Errors

If the function returns AT_FAILUREP, use the SRL Standard Attribute functionATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) toobtain a descriptive error message. See Appendix A - Standard Runtime Libraryfor more information on SRL functions. The error codes returned byATDV_LASTERR( ) are:

• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid or undefined command to driver• EDT_INVBD - invalid digital network interface logical board device handle• EDT_INVMSG - invalid message• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_RANGEERR - bad/overlapping physical memory range• EDT_SIZERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - System error - check the global variable errno for more

information about the error• EDT_TMOERR - timed out waiting for reply from firmware


! See Also

• ATDT_BDMODE( )• ATDT_TSMODE( )• ATDT_TSSGBIT( )• dt_setsigmod( )• dt_settssig( )

returns the firmware version ATDT_DNLDVER( )

39

Name: long ATDT_DNLDVER(devh) Inputs: int devh • digital network interface

logical board device handle Returns: version of firmware used by the device



Mode: synchronous

! Description

The ATDT_DNLDVER( ) function returns the firmware version downloaded tothe device specified in devh. This number is returned in the standard versionnumbering format.



Version Numbering

A version number consists of two parts that provide:

1. The release TYPE (Example: Production or Beta

2. The release NUMBER, which consists of different elements depending onthe type of release, for example:

• 1.00 Production• 1.00 Beta 5

NOTE: The examples above are shown in the convention used to displayversion numbers.

This function returns the version number as a long integer (32 bits) in BCD(binary coded decimal) format.

Figure 11 shows the format of the version number returned. Each section in thediagram represents a nibble (4 bits).

ATDT_DNLDVER( ) returns the firmware version

40

1 2 876543

long int (8 nibbles = 32 bits)

MSB

Type ProductionNumber

InternalNumber

Figure 11. Firmware Version Number Format

Nibble 1 returns the type of release in BCD numbers. A converted value of 0indicates a Production release and a converted value of 1 indicates a Beta release.

Nibbles 2, 3, and 4 return the Production Release Number.

NOTE: Nibbles 2 through 4 are used in all version numbers. Nibbles 5 through8 only contain values if the release is not a production release.

Nibbles 5, 6, 7, and 8 return the Internal Release Number used for pre-productionproduct releases. Nibbles 5 and 6 hold the product�s Beta number. Nibbles 7 and8 hold additional information used for internal releases.

Table 2 displays a breakdown of the values returned by each nibble in the longinteger.


41

Table 2. ATDT_DNLDVER( ) Return Values

Nibble (4 bits)1 2 3 & 4 5 & 6 7 & 8

TYPE PRODUCTION RELEASENUMBER

INTERNAL NUMBER

Production MajorRelease No.

MinorRelease No.

N/A N/A

Beta MajorRelease No.

MinorRelease No.

Beta Number N/A

Major and Minor Release Numbers

Major and minor release numbers distinguish major revisions from minorrevisions to Production releases. The major number converts to a single digitinteger that increments with each major revision to the release. The minornumber converts to a two digit integer that increments with each minor revisionto the release.

In decimal number format, the major number is the number before the decimalpoint, and the minor number is the number after the decimal point.

The following list gives examples of each type of release. The values used inthese examples have been converted from the binary coded decimal numbersreturned in the long integer and are displayed according to the convention.


! Cautions

This function will fail if an invalid digital network interface logical board devicehandle is specified.

ATDT_DNLDVER( ) returns the firmware version

42

! Example

#include <windows.h> /* For Windows applications only */ #include <stdio.h> #include <srllib.h> #include <dtilib.h> #include <errno.h>

void main() { int bdev; long version;

if ((bdev = dt_open("dtiB1", 0)) == -1) { printf("Error in dt_open\n"); }

/* Get the version number */ version = ATDT_DNLDVER(bdev);

if (version == AT_FAILURE) { printf("ERROR in getting version #\n"); } else { /* display the version # */ printf("DTI version number is %x.%02x ", (int) ((version >>24)&0x0F), ((version >> 16)&0xFF));

// check for the download type switch (version >> 28) { case 0: printf("beta %02x \n", ((version >> 16)&0xFF));

case 1: printf("production\n"); } // end switch }

dt_close(bdev); printf("\nend of prog\n"); }


43

! Errors


• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid command parameter to driver• EDT_INVBD - invalid digital network interface logical board device handle• EDT_INVMSG - invalid message• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_RANGERR - bad/overlapping physical memory range• EDT_SIZEERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - System error. Check the global variable errno for more



! See Also

• ATDT_ROMVER( )

ATDT_IDLEST( ) returns the current idle state

44

Name: long ATDT_IDLEST(devh) Inputs: int devh • digital network interface

logical time slot device handle Returns: idling state of time slot



Mode: synchronous

! Description

The ATDT_IDLEST( ) function returns the current idle state of the digitalnetwork interface time slot specified in devh. �Idling� transmits silence to thenetwork for the selected time slot.


devh: Specifies the valid digital network interface logical timeslot device handle returned by a call to dt_open( )

The following defines are provided in dtilib.h.

• DTIS_ENABLE - silence insertion is enabled• DTIS_DISABLE - silence insertion is disabled

To determine if a time slot is idling, compare the value of the returned integerwith the provided defines.

! Cautions

This function will fail if an invalid digital network interface logical time slotdevice handle is specified.

returns the current idle state ATDT_IDLEST( )

45

! Example


main() { int devh; /* Time slot device handle */ long mode; /* Time slot idle state mode */

/* * Open board 1 time slot 1 device */ if ( ( devh = dt_open( "dtiB1T1", 0 ) ) == -1 ) { printf( "Cannot open time slot dtiB1T1. errno = %d", errno ); exit( 1 ); }

/* * Get silence insertion mode */ if ( ( mode = ATDT_IDLEST( devh ) ) == AT_FAILURE ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); }

switch ( mode ) { case DTIS_ENABLE: printf( "Time slot 1 on board 1 has silence insertion enabled\n" ); break; case DTIS_DISABLE: printf( "Time slot 1 on board 1 has silence insertion disabled\n" ); break; } . . . }

ATDT_IDLEST( ) returns the current idle state

46

! Errors


• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid command parameter to driver• EDT_INVTS - invalid digital network interface logical time slot device

handle• EDT_INVMSG - invalid message• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_RANGERR - bad/overlapping physical memory range• EDT_SIZEERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - System error. Check the global variable errno for more



! See Also

• dt_setidle( )

returns the version of the EPROM ATDT_ROMVER( )

47

Name: long ATDT_ROMVER(devh) Inputs: int devh • digital network interface

logical board device handle Returns: version of EPROM installed on digital network interface

deviceAT_FAILURE if function fails

Includes: srllib.hdtilib.h

Category: Extended Attribute Mode: synchronous

! Description

The ATDT_ROMVER( ) function returns the version of the EPROM that isinstalled on the digital network interface device specified in devh. This numberis returned in the standard version numbering format. This function is notavailable on DIALOG/HD boards.


devh: Specifies the valid digital network interface logical boarddevice handle returned by a call to dt_open( ).

Version Numbering

A version number consists of two parts that provide:

1. The release TYPE (Example: Production or Beta

2. The release NUMBER, which consists of different elements depending onthe type of release, for example:


NOTE: The examples above are shown in the convention used to displayversion numbers.

This function returns the version number as a long integer (32 bits) in BCD(binary coded decimal) format.

ATDT_ROMVER( ) returns the version of the EPROM

48

Figure 12 shows the format of the version number returned. Each section in thediagram represents a nibble (4 bits).

1 2 876543

long int (8 nibbles = 32 bits)

MSB

Type ProductionNumber

InternalNumber

Figure 12. EPROM Version Number Format

Nibble 1 returns the type of release in BCD numbers. A converted value of 0indicates a Production release and a converted value of 1 indicates a Beta release.

Nibbles 2, 3, and 4 return the Production Release Number.

NOTE: Nibbles 2 through 4 are used in all version numbers. Nibbles 5 through8 only contain values if the release is not a production release.

Nibbles 5, 6, 7, and 8 return the Internal Release Number used for pre-productionproduct releases. Nibbles 5 and 6 hold the product�s Beta number. Nibbles 7 and8 hold additional information used for internal releases.

Table 3 displays a breakdown of the values returned by each nibble in the longinteger.


49

Table 3. ATDT_ROMVER( ) Return Values

Nibble (4 bits)1 2 3 & 4 5 & 6 7 & 8

TYPE PRODUCTION RELEASENUMBER

INTERNAL NUMBER

Production MajorRelease No.

MinorRelease No.

N/A N/A

Beta MajorRelease No.

MinorRelease No.

Beta Number N/A

Major and Minor Release Numbers

Major and minor release numbers distinguish major revisions from minorrevisions to Production releases. The major number converts to a single digitinteger that increments with each major revision to the release. The minornumber converts to a two digit integer that increments with each minor revisionto the release.

In decimal number format, the major number is the number before the decimalpoint, and the minor number is the number after the decimal point.

The following list gives examples of each type of release. The values used inthese examples have been converted from the binary coded decimal numbersreturned in the long integer and are displayed according to the convention.


! Cautions

This function will fail if an invalid digital network interface logical board devicehandle is specified.

ATDT_ROMVER( ) returns the version of the EPROM

50

! Example


main() { int devh; /* Board device handle */ long version; /* Version number of EPROM */


/* * Get the version number of the EPROM */ version = ATDT_ROMVER( devh ); if ( version == AT_FAILURE ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); }

/* * Display it */ printf( "DTI/2xx EPROM version number is %d.%02x\n", (int)((version>>24)&0x0F), ((version >>16)&0xFF) ); . . . }


51

! Errors


• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid command parameter to driver• EDT_INVBD - invalid digital network interface logical board device handle• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_RANGERR - bad/overlapping physical memory range• EDT_SIZEERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - system error - check the global variable errno for more



! See Also

• ATDT_DNLDVER( )

ATDT_STATUS( ) returns the current status

52

Name: long ATDT_STATUS(devh) Inputs: int devh • digital network interface

logical time slot device handle Returns: status of time slot



Mode: synchronous

! Description

The ATDT_STATUS( ) function returns the current status of the digital networkinterface time slot specified in devh.



The following defines are provided:

• DTST_INACTIVE - time slot is idle• DTST_BUSY - time slot is not idle

To determine the status of the time slot, compare the value of the returned integerwith the defines listed above.

The time slot is considered busy if it is currently executing a multitaskingfunction, for example, wink signaling.

! Cautions


! Example

#include <windows.h> /* For Windows applications only */ #include <srllib.h>

returns the current status ATDT_STATUS( )

53

#include <dtilib.h> #include <errno.h>

main() { int devh; /* Time slot device handle */ long mode; /* Current status of time slot */


/* * Get current wink status of time slot */ if ( ( mode = ATDT_STATUS( devh ) ) == AT_FAILURE ) { printf( "Error message = %s.", ATDV_ERRMSGP( devh ) ); exit( 1 ); }

/* * Display it */ switch ( mode ) { case DTST_INACTIVE: printf( "Time slot 1 on board 1 is idle\n" ); break; case DTST_BUSY: printf( "Time slot 1 on board 1 is busy\n" ); break; } . . . }

ATDT_STATUS( ) returns the current status

54

! Errors


• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid command parameter to driver• EDT_INVMSG - invalid message• EDT_INVTS - invalid digital network interface logical time slot device

handle• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_RANGERR - bad/overlapping physical memory range• EDT_SIZEERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - system error. Check the global variable errno for more



! See Also

• dt_xmitwink( )

returns the current signaling mode ATDT_TSMODE( )

55

Name: long ATDT_TSMODE(devh) Inputs: int devh • digital network interface

logical time slot device handle Returns: time slot signaling mode



Mode: synchronous

! Description

The ATDT_TSMODE( ) function returns the current signaling mode of the timeslot specified in devh.



The following defines are provided in dtilib.h.

• DTM_SIGINS - signaling insertion mode (digital network interface boardgenerates signaling to network)

To determine the signaling mode of a specified time slot, compare the returnedvalue with the defines listed above.

! Cautions1. This function will fail if an invalid digital network interface logical time slot


2. For returned values to be valid, you must call dt_setsigmod( ) first

ATDT_TSMODE( ) returns the current signaling mode

56

! Example


main() { int devh; /* Time slot device handle */ long mode; /* Time slot signaling mode */


/* * Get current time slot signaling mode */ if ( ( mode = ATDT_TSMODE( devh ) ) == AT_FAILURE ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); }

/* * Display it */ switch ( mode ) { case DTM_SIGINS: printf( "Time slot 1 on board 1 has signaling insertion\n" ); break; case DTM_TRANSP: printf( "Time slot 1 on board 1 has signaling transparent\n" ); break; } . . . }

returns the current signaling mode ATDT_TSMODE( )

57

! Errors






! See Also

• ATDT_BDSGBIT( )• ATDT_BDMODE( )• dt_setsigmod( )• dt_settssig( )

ATDT_TSSGBIT( ) retrieves the current state

58

Name: long ATDT_TSSGBIT(devh) Inputs: int devh • digital network interface

logical time slot device handle Returns: state of time slot signaling bits



Mode: synchronous

! Description

The ATDT_TSSGBIT( ) function retrieves the current state of the transmit andreceive signaling bits for the time slot specified by devh.



The returned bitmask represents the following signaling bits:

• DTSG_RCVA - �A� receive signaling bit• DTSG_RCVB - �B� receive signaling bit• DTSG_RCVC - �C� receive signaling bit (E1 only)• DTSG_RCVD - �D� receive signaling bit (E1 only)• DTSG_XMTA - �A� transmit signaling bit• DTSG_XMTB - �B� transmit signaling bit• DTSG_XMTC - �C� transmit signaling bit (E1 only)• DTSG_XMTD - �D� transmit signaling bit (E1 only)

To determine the state of the signaling bits for the specified time slot, perform alogical AND operation on the byte buffer and the defines, as demonstrated in theexample below.

retrieves the current state ATDT_TSSGBIT( )

59

! Cautions1. This function will fail if an invalid digital network interface logical time slot


2. The transmit signaling bits are only valid when the device is in signalinginsertion mode.

! Example

#include <windows.h> /* For Windows applications only */ #include <srllib.h> #include <dtilib.h> #include <errno.h> main() { int devh; /* Time slot device handle */ long tsbits; /* Time slot signaling bits */ int arcv, brcv, axmt, bxmt; /* Bit mask values */ /* * Open board 1 time slot 1 device */ if ( ( devh = dt_open( "dtiB1T1", 0 ) ) == -1 ) { printf( "Cannot open time slot dtiB1T1. errno = %d", errno ); exit( 1 ); } /* * Get time slot signaling bits */ tsbits = ATDT_TSSGBIT( devh ); if ( tsbits == AT_FAILURE ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } /* * Display it */ arcv = ( tsbits & DTSG_RCVA ) ? 1 : 0; brcv = ( tsbits & DTSG_RCVB ) ? 1 : 0; axmt = ( tsbits & DTSG_XMTA ) ? 1 : 0; bxmt = ( tsbits & DTSG_XMTB ) ? 1 : 0; printf( "tslot 1 arcv = %d, brcv = %d, axmt = %d, bxmt = %d\n", arcv, brcv, axmt, bxmt ); . . . }

ATDT_TSSGBIT( ) retrieves the current state

60

! Errors






! See Also

• ATDT_BDSGBIT( )• ATDT_BDMODE( )• ATDT_TSMODE( )• dt_setsigmod( )• dt_settssig( )

manage the CAS DTI templates dt_castmgmt( )

61

Name: int dt_castmgmt (devh,cmdmsgp, replymsgp) Inputs: int devh • valid DTI board or time slot

device handle void *cmdmsgp • pointer to command message

block void *replymsgp • pointer to reply message block

buffer Returns: 0 on success

-1 on failure Includes: dtilib.h

ditcas.h Category: I/O

Mode: synchronous

! Description

The dt_castmgmt( ) function is used to manage the CAS DTI templates used forthe detection and transmission of signaling patterns with precise time intervals.Timing constraints in signaling protocols may make it very difficult to detect ortransmit a signal at the application level and respond quickly. It is also difficultto ensure accurate timing between signal transitions, pulses or trains. Thisfunction allows the application to predefine a signal set (a set templates of signaltransitions, pulses and/or trains and times to remain at each signal state) in theboard�s firmware, effectively offloading signal detection and transmission fromthe host. Signal templates, once created, apply to all channels on a board. Eachsignal template is enabled or disabled on a per channel basis. The signaldetection and transmission characteristics are communicated to the board via thecommand message blocks describe below.

Each template created for a signal set must have a distinct identifier. The creationand deletion of a template is initiated by a command from the application. Thechanging of the parameters of a template is done by deleting the old template andadding a new template. Once defined, each template has all channels disabled,and must be enabled or disabled individually for each channel which it isintended. If a template is deleted by the application, all signal matching ortransmission for that template on all channels is abandoned and the applicationwill not be notified. If a template is disabled on a specific channel by theapplication, all signal matching or transmission for that template on that specificchannel is abandoned and the application will not be notified.

dt_castmgmt( ) manage the CAS DTI templates

62

For signal detection, once a template is enabled on a channel, all incomingsignaling changes are matched against the template on that channel. If more thanone template is enabled on a channel, incoming signaling changes are matchedagainst all templates on that channel. As soon as all the parameters on atemplate(s) are matched, an unsolicited event (DTEV_CASTEVT) is sent to theapplication. The event data contains the identifier of the template that wasdetected. The firmware will send the event each time a transition, pulse or trainof pulses is received and validated.

For signal transmission, once a template is defined and enabled, an applicationcan transmit signals matching that template using a subcommandDTCAS_TRANSMIT_TEMPLATE. The board immediately acknowledges thesend command with DTCAS_TRANSMIT_TEMPLATE_COMPLETE. Theapplication receives an unsolicited event (DTEV_CASSENDENDEVT) aftersend command succeeds.

Signal detection or transmission is terminated when any of the followingconditions are satisfied:

• The template is disabled or deleted• A change in the detected signal is detected

This function operates in the synchronous (blocking) mode, however, signaldetection or transmission once enabled, occurs asynchronously. All datastructures used for creating a template, deleting a template, enabled a template,disabling a template, detecting a signal, and transmitting a signal are defined indticas.h.


devh Specifies the valid board or time slot device handlereturned by the call to dt_open( ). The type of handledepends on the cmdmsgp argument.

cmdmsgp Points to the command message block. Descriptions ofvalid command message blocks are listed in Appendix B -Message Blocks. Although the number of fields and theirmeaning are different for each command message block,they all contain one or more of the data types described inthe Common Data Types section.


63


replymsgp Points to the reply message block buffer supplied by theapplication. If the function returns 0, this buffer is filledwith the reply message block. Descriptions of the replymessage block expected by each command is listed inAppendix B - Message Blocks. Although the number offields and their meaning are different for each replymessage block, they all contain one or more of the datatypes described in the Common Data Types section.

WARNING The application is responsible for allocating a reply message block

buffer of sufficient length.

If event handling is set up properly for your application, the sr_getevttype( )function included in the SRL will return DTEV_CASTEVT, when a signalpattern match occurs and DTEV_CASSENDENDEVT, when signaltransmission is complete . The DTEV_CASTEVT andDTEV_CASTSENDENDEVT event blocks are described in Appendix B -Message Blocks.

Although each message block is different, they all contain one or more of thefollowing data types, however, there are three fields that are common to eachparameter follows:

Table 4. Common Data Types

template_id A template identifier which is a two byte quantity with noimplicit value or order. It is used to identify the template inrecognition events and to select the template in transmissioncommands. The application is free to use it for any uniqueidentifier. However, it is recommended that the followingconvention be used: The 2-byte template IDs should consist ofthe high byte being a protocol number and the low byte beingthe template �meaning� (1=idle, 2=ring, 3=seize, etc.).

prefixCode The signal pattern for matching and setting templates. This is a


64

bit pattern that represents the signaling bits, and is used as abuilding block to specify templates. This parameter is similar tothe dt_settssigsim( ) bitmask. The prefixCode can be 0 or alogical OR of one or more of the following values:

• DTB_AON - �A� signaling bit on• DTB_AOFF - �A� signaling bit off• DTB_BON - �B� signaling bit on• DTB_BOFF - �B� signaling bit off• DTB_CON - �C� signaling bit on (E1 only)• DTB_COFF - �C� signaling bit off (E1 only)• DTB_DON - �D� signaling bit on (E1 only)• DTB_DOFF - �D� signaling bit off (E1 only)

NOTE: It is incorrect to OR ON and OFF states for the samesignaling bit, i.e., it is incorrect to OR DTB_AON andDTB_AOFF. The ON state will be the one matched.

prefixInterval The time interval. Time intervals are specified in units of 1ms,however due to the internal clock mechanism this value mayvary ±5ms. The maximum value that can be specified is 63seconds.

! Cautions1. The dt_settssigsm( ) function must be used to set the state of the channel's

signaling bits prior to sending any CAS templates via a call todt_castmgmt( ). The user must set the channel�s signaling bits to the statespecified in the PreTransCode parameter value prior to sending a transitionor to the OffPulseCode parameter value when sending a pulse or train. Theuser must also ensure that the pattern is transmitted for the amount of timespecified by the PreTransInterval, PrePulseInterval, or PreTrainIntervalparameter of the DTCAS_CREATE_TRANSITION,DTCAS_CREATE_PULSE, or DTCAS_CREATE_TRAIN commandmessage blocks, respectively.

2. This function will fail under the following conditions:• An invalid device handle is specified• Signaling insertion is not enabled; the time slot must be in signaling

insertion mode before this function is called. Signaling insertion modeis enabled using the dt_setsigmod( ) function.


65

• An application initiates a transmit command before the completion of aprogressing transmission


66

! Example

// This program uses a D/480 or D/600 to demonstrate how CAS templates work.

#include "stdafx.h"#include <stdio.h>#include <errno.h>#include "srllib.h"#include "dtilib.h"

#include <windows.h>#include <winbase.h>#include <stdio.h>#include <process.h>#include <stddef.h>#include <stdlib.h>#include <string.h>#include <conio.h>

#define USEREVT_KEYBOARD 1 /*User defined keyboard event */

int Kbhit_flag = 0;void CheckKey( void *dummy );int process(int,long);

int main(int argc, char* argv[]){

int srlmode,x; int devh, devh2; /* DTI board device descriptor */ int tsdevh, tsdevh2; /* DTI channel device descriptor */ DTCAS_CREATE_TRAIN_MSG cpmsg; /* Create train template message */ DTCAS_REPLY_MSG cpcmsg; /* Reply buffer for Train template complete message */ DTCAS_ENA_DIS_TEMPLATE_MSG etmsg; /* Enable template message */ DTCAS_REPLY_MSG etcmsg; /* Reply buffer for enable template complete message */ DTCAS_TRANSMIT_MSG tmsg; /*Transmit train template message*/ DTCAS_REPLY_MSG tcmsg; /* Reply buffer for Train template transmit complete message */ DTCAS_DELETE_TEMPLATE_MSG dmsg; /*Delete train template message*/ DTCAS_REPLY_MSG dcmsg; /* Reply buffer for delete train template complete message */ int evtdev; long evttype;

/* Launch CheckKey thread to check for terminating keystroke. */ _beginthread( CheckKey, 0, NULL );

/* * Set SRL to run in polled mode. */ srlmode = SR_POLLMODE; if (sr_setparm(SRL_DEVICE,SR_MODEID,&srlmode) == -1) { fprintf(stderr,"ERROR: Failed to set SRL in SR_POLLMODE\n"); exit(1); }


67

/* * Open DTI board devices. */ if ((devh = dt_open("dtiB1",0)) == -1) { fprintf(stderr,"Cannot open dtiB1: error=%d", errno); exit(1); } if ((devh2 = dt_open("dtiB2",0)) == -1) { fprintf(stderr,"Cannot open dtiB2: error=%d", errno); dt_close(devh); exit(1); }

/* * Open DTI board 1, tslot 1. */ if ((tsdevh = dt_open("dtiB1T1",0)) == -1) { fprintf(stderr,"Cannot open dtiB1T1: errno=%d", errno); dt_close(devh); dt_close(devh2); exit(1); }

/* * Open DTI board 2, tslot 1. */ if ((tsdevh2 = dt_open("dtiB2T1",0)) == -1) { fprintf(stderr,"Cannot open dtiB2T1: errno=%d", errno); dt_close(devh); dt_close(devh2); dt_close(tsdevh); exit(1); }

/* * Set signaling mode to signaling insertion */ if (dt_setsigmod(tsdevh, DTM_SIGINS) == -1) { fprintf(stderr,"dt_setsigmod ERROR %d: %s\n", ATDV_LASTERR(tsdevh),ATDV_ERRMSGP(tsdevh)); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); } if (dt_setsigmod(tsdevh2, DTM_SIGINS) == -1) { fprintf(stderr,"dt_setsigmod ERROR %d: %s\n", ATDV_LASTERR(tsdevh),ATDV_ERRMSGP(tsdevh2)); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); }


68

/* * Define a Train using the Train template message block. */

cpmsg.msg_code = DTCAS_CREATE_TRAIN; cpmsg.rfu = 0; cpmsg.template_id = 1; cpmsg.OffPulseCode = (DTB_AON|DTB_BOFF); cpmsg.OnPulseCode = (DTB_AOFF|DTB_BON); cpmsg.PreTrainInterval = 1200; cpmsg.PreTrainIntervalNom = 1300;

cpmsg.PulseIntervalMin = 1200; cpmsg.PulseIntervalNom = 1500; cpmsg.PulseIntervalMax = 1700;

cpmsg.InterPulseIntervalMin = 1000; cpmsg.InterPulseIntervalNom = 1200; cpmsg.InterPulseIntervalMax = 1400;

cpmsg.PostTrainInterval = 1500; cpmsg.PostTrainIntervalNom = 1700;

// Set up the signalling bits per the template - if ( dt_settssigsim( tsdevh, DTB_AON | DTB_BOFF ) == -1) { printf("dt_settssigsim failed - Error message = %s.", ATDV_ERRMSGP( devh ) ); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); } else printf("Set Bits on dtiB2T1\n");

//Hold the pattern for at least 1200 ms Sleep(1200);

// //Add train template to signal set. // if (( x=dt_castmgmt(devh, &cpmsg, &cpcmsg)) == -1) { fprintf(stderr,"Error Message (Add train template to signal set) on board 1= %x, %s\n",ATDV_LASTERR(devh),ATDV_ERRMSGP(devh)); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); } else printf(" dt_castmgmt result = %x\n",x); // //Check if operation was successful. // printf("on board 1: msg_code = %d, rfu = %d , template_id = %d, result = 0x%x\n", cpcmsg.msg_code, cpcmsg.rfu, cpcmsg.template_id, cpcmsg.result); if (cpcmsg.result != 0)


69

{ fprintf(stderr,"Add train template to signal set failed. \n"); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); }

if (dt_castmgmt(devh2, &cpmsg, &cpcmsg) == -1) { fprintf(stderr,"Error Message (Add train template to signal set) on board 2 = %s",ATDV_ERRMSGP(devh2)); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); }

// // Check if operation was successful. // printf("on board 2: msg_code = %d, rfu = %d , tempate_id = %d, result = %x\n", cpcmsg.msg_code, cpcmsg.rfu, cpcmsg.template_id, cpcmsg.result); if (cpcmsg.result != 0) { fprintf(stderr," Add train template to signal set failed. "); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); } /* * Enable template id 1. */ etmsg.msg_code = DTCAS_ENABLE_TEMPLATE; etmsg.rfu = 0; etmsg.template_id = 1;

/* * Enable template. */ if (dt_castmgmt(tsdevh, &etmsg, &etcmsg) == -1) { printf("Error Message (Enable template) on board 1 = %s",ATDV_ERRMSGP(tsdevh)); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); } /* * Check if the operation was successful. */ printf("on board 1: msg_code = %d, rfu = %d , tempate_id = %d, result = %x\n", etcmsg.msg_code, etcmsg.rfu, etcmsg.template_id, etcmsg.result); if (etcmsg.result != 0) { fprintf(stderr," Enable template failed.\n" ); dt_close(tsdevh);


70

dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); }

if (dt_castmgmt(tsdevh2, &etmsg, &etcmsg) == -1) { printf("Error Message (Enable template) on board 2 = %s",ATDV_ERRMSGP(tsdevh2)); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); }

/* * Check if the operation was successful. */ printf("on board 2: msg_code = %d, rfu = %d , tempate_id = %d, result = %x\n", etcmsg.msg_code, etcmsg.rfu, etcmsg.template_id, etcmsg.result); if (etcmsg.result != 0) { fprintf(stderr,"Enable template failed. Error = %s",ATDV_ERRMSGP(tsdevh2)); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); }

/* * Send Signal for Template ID 1. */ tmsg.msg_code = DTCAS_TRANSMIT_TEMPLATE; tmsg.rfu = 0; tmsg.template_id = 1; tmsg.pulse_count = 2;

/* * Send template. */ if (dt_castmgmt(tsdevh, &tmsg, &tcmsg) == -1) { printf("Error Message (Send template) On Board 1 = %s",ATDV_ERRMSGP(tsdevh)); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); } /* * Check if the operation was successful. */ printf("on board 1: msg_code = %d, rfu = %d , tempate_id = %d, result = %x\n", tcmsg.msg_code, tcmsg.rfu, tcmsg.template_id, tcmsg.result); if (tcmsg.result != 0) { fprintf(stderr," Send template failed.\n"); dt_close(tsdevh); dt_close(devh);


71

dt_close(tsdevh2); dt_close(devh2); exit(1); }

/*While no keyboard input, keep cycling through functions */ while (1) { /*Wait for events */ sr_waitevt(-1); evtdev = sr_getevtdev(); evttype = sr_getevttype(); if ((evtdev == SRL_DEVICE) && (evttype == USEREVT_KEYBOARD)) break; if (process(evtdev, evttype) != 0) break; }

// delete template and close ts and board dmsg.msg_code = DTCAS_DELETE_TEMPLATE; dmsg.rfu = 0; dmsg.template_id =1;//DTCAS_CLEAR_ALL_TEMPLATE

if (dt_castmgmt(tsdevh, &dmsg, &dcmsg) == -1) { printf("Error Message (deleting template) on board 1= %s",ATDV_ERRMSGP(tsdevh)); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); } /* * Check if the operation was successful. */ printf("on board 1: msg_code = %d, rfu = %d , template_id = %d, result = 0x%x\n", dcmsg.msg_code, dcmsg.rfu, dcmsg.template_id, dcmsg.result); if (dcmsg.result != 0) { fprintf(stderr," Deleting template failed. \n"); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); } if (dt_castmgmt(tsdevh2, &dmsg, &dcmsg) == -1) { printf("Error Message (deleting template) on board 2= %s",ATDV_ERRMSGP(tsdevh2)); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); } /* * Check if the operation was successful. */ printf("on board 2: msg_code = %d, rfu = %d , template_id = %d, result = 0x%x\n", dcmsg.msg_code, dcmsg.rfu, dcmsg.template_id, dcmsg.result); if (dcmsg.result != 0)


72

{ fprintf(stderr," Deleting template failed. \n"); dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); exit(1); }

dt_close(tsdevh); dt_close(devh); dt_close(tsdevh2); dt_close(devh2); return 0;}

/**************************************************************************** NAME: int process( eventdev, event )* DESCRIPTION: Do the next function depending on the Event Received* INPUT: int eventdev; - Device on which event was received* int event; - Event being processed* OUTPUT: None* RETURNS: New Channel State* CAUTIONS: None***************************************************************************/int process( int tsdev, long event ){ int len = sr_getevtlen(); DTCAS_DETECTED_MSG *dmsgp1; DTCAS_END_TRANSMIT_MSG *dmsgp2;

switch ( event ) { case DTEV_CASTEVT: printf("%s: Signaling completed ", ATDV_NAMEP(tsdev)); dmsgp1 = (DTCAS_DETECTED_MSG *)sr_getevtdatap(); printf("DTEV_CASTEVT detected Template %d\t message code = %d\tResult Code = %d\n",dmsgp1->template_id,dmsgp1->msg_code,dmsgp1->result); break; case DTEV_CASSENDENDEVT: printf("%s: Signal Transmission completed ", ATDV_NAMEP(tsdev)); dmsgp2 = (DTCAS_END_TRANSMIT_MSG *)sr_getevtdatap(); printf("DTEV_CASSENDENDEVT detected Template %d\n",dmsgp2->template_id); break; default: fprintf(stderr,"%s: EVENT ERROR: Unknown event = 0x%lx\t Data Length = %d\n",ATDV_NAMEP(tsdev),sr_getevttype(),len); break; } return 0;}

/**************************************************************************** NAME: DWORD WINAPI keyboard_monitor( LPVOID argp )* DESCRIPTION: Wait for keyboard input* INPUT: LPVOID argp* OUTPUT: None


73

* RETURNS: none* CAUTIONS: None***************************************************************************/void CheckKey( void *dummy ){ int ch; printf("Press 'q' to quit\n"); do { ch= _getch(); if (ch=='q') { sr_putevt(SRL_DEVICE,USEREVT_KEYBOARD,0,NULL,0); } else printf("\n"); }while (ch!='q');

/* _endthread given to terminate */ _endthread();

}

! Errors

If this function returns -1 to indicate failure, use ATDV_LASTERR( ) andATDV_ERRMSGP( ) to retrieve one of the following error types.

• EDT_BADBRDERR - DTI/2xx missing or defective• EDT_BADCMDERR - Invalid or undefined command to driver• EDT_DATTO - Data reception timed out• EDT_FWERR - Firmware returned an error• EDT_PARMERR - Invalid parameter• EDT_RANGEERR - Bad/overlapping physical memory range• EDT_SIZERR - Message too big or too small• EDT_SKIPRPLYERR - A required reply was skipped• EDT_SYSTEM - System error - check the global variable errno for more

information about the error• EDT_TMOERR - Timed out waiting for reply from firmware• EDT_INVTS - Invalid time slot device handle• EDT_SIGINS - Signaling insertion not enabled• EDT_INVMSG - Invalid message

dt_castdecode( ) decode the CAS DTI reply or event message block

74

Name: int dt_castdecode (msgp, decmsgbufp) Inputs: void *msgp • pointer to encoded message

block void *decmsgbufp • pointer to destination buffer of

decoded message block Returns: 0 on success

-1 on failure Includes: dtilib.h Category: CAS DTI Convenience

Mode: synchronous

! Description

The dt_castdecode( ) function is called internally by the DTI event retriever foreach CAS DTI reply or event message block that occurs. Its purpose is to decodethe CAS DTI reply or event message block before it is given to dt_castmgmt( )or the application, respectively. This function is offered to localize the tasks ofhost system issues (i.e. byte swapping) and message formation with regards tomessages that are passed across the host system bus.

The dt_castdecode( ) function takes as its first parameter a CAS DTI messageblock. It will use the decmsgbufp parameter to return the decoded messageblock. The operation of this function does not prevent msgp and decmsgbufpfrom being the same buffer.

! Example

#include "dtilib.h" … /* * This is a code fragment demonstrating * the use of the _dt_castdecode() function. */ …

/* * Read CAS DTI message block from driver. */ …

/* * Decode the CAS DTI message block * before interrogating its contents. *

decode the CAS DTI reply or event message block dt_castdecode( )

75

* Note: The CAS DTI message block should * not be manipulated until after this point. */ if ((n = _dt_castdecode(msgp, msgp)) == -1) { ndt_set_lasterr(devh, EDT_INVMSG); return -1; } …

! Errors

This function returns -1 if it does not recognize the msg_code field the reply orevent message block.

! See Also

• dt_castencode( )

dt_castencode( ) validate and encode the message

76

Name: int dt_castencode (msgp, encmsgbufp) Inputs: void *msgp • pointer to command message

block to encode void *encmsgbufp • pointer to destination buffer of

encoded message block Returns: 0 on success

-1 on failure Includes: dtilib.h Category: CAS DTI Convenience

Mode: synchronous

! Description

The dt_castencode( ) function is called internally by dt_castmgmt( ). For everyCAS DTI command message block passed to dt_castmgmt( ), thedt_castencode( ) function is called to validate and encode the message before itis written to the firmware. This function is offered to localize the tasks of hostsystem issues (i.e. byte swapping) and message formation regarding messagesthat are passed across the host system bus.

The dt_castencode( ) function takes as its first parameter a command messageblock. It will use the encmsgbufp parameter to return the validated/encodedmessage block. Direct modification of the encoded message block is not allowed.The operation of this function does not prevent msgp and encmsgbufp frombeing the same buffer.

! Example

#include "dtilib.h" … /* * This is a code fragment demonstrating * the use of the _dt_castencode() function. */ …

/* * Define a pulse using the pulse template message block. */ cpmsg.msg_code = DTCAS_CREATE_PULSE; cpmsg.flags = 0; cpmsg.template_id = 1; cpmsg.OffPulseCode = (DTB_AON|DTB_BOFF); cpmsg.OnPulseCode = (DTB_AOFF|DTB_BON);

validate and encode the message dt_castencode( )

77

cpmsg.PrePulseInterval = 0; cpmsg.PrePulseIntervalNom = 0; cpmsg.PulseIntervalMin = 120; cpmsg.PulseIntervalNom = 150; cpmsg.PulseIntervalMax = 170; cpmsg.PostPulseInterval = 0; cpmsg.PostPulseIntervalNom = 0;

/* * Encode the create pulse template message block * before sending to the driver. * * Note: The create pulse template message should * not be manipulated after this point unless it * is decoded. */ if ((n = _dt_castencode(&cpmsg, &cpmsg)) == -1) { ndt_set_lasterr(devh, EDT_BADCMDERR); return -1; }

/* * Write to driver. */ …

! Errors

This function returns -1 if it does not recognize the msg_code field in thecommand message block.

! See Also

• dt_castdecode( )

dt_close( ) closes digital network interface devices

78

Name: int dt_close(devh) Inputs: int devh • digital network interface

logical board or digitalnetwork interface logical timeslot device handle

Returns: 0 on success-1 on failure


Category: Resource Management Mode: synchronous

! Description

The dt_close( ) function closes digital network interface devices openedpreviously by a call to dt_open( ). The specified device may be either a digitalnetwork interface logical board or time slot device. The dt_close( ) functionreleases the handle and breaks the link between the calling process and thedevice.


devh: Specifies the valid digital network interface logical boardor digital network interface logical time slot device handlereturned by a call to dt_open( )

! Cautions1. This function will fail if the device handle is invalid.

2. The dt_close( ) function affects only the link between the calling process andthe device. Other processes are unaffected by dt_close( ).

3. If event notification is active for the device to be closed, call the SRLsr_dishdlr( ) function prior to calling dt_close( ).

4. A call to dt_close( ) does not affect the configuration of the device.

5. Devices should never be closed using the close( ) function.

closes digital network interface devices dt_close( )

79

! Example


main() { int devh; /* Board device handle */


/* * Continue processing */ . . . /* * Done processing - close device. */

if ( dt_close( devh ) == -1 ) { printf( "Cannot close board dtiB1. errno = %d", errno ); } }

! Errors

If the function returns -1, use the SRL Standard Attribute functionATDV_LASTERR( ) to obtain the following error value:

• EDT_SYSTEM - system error - check the global variable errno for moreinformation about the error.

! See Also

• dt_open( )

dt_dial( ) allows the application to pulse dial

80

Name: int dt_dial(devh,digstr,tmo) Inputs: int devh • time slot device handle

char *digstr • pointer to an ASCIIZ string ofdigits

unsigned int tmo • timeout value Returns: 0 on success

-1 on failure Includes: srllib.h

dtilib.h Category: Time Slot Signaling

Mode: synchronous/asynchronous

! Description

The dt_dial( ) function allows the application to pulse dial an ASCIIZ string ofdigits on a specified D/240SC-T1, D/240SC-2T1, D/480SC-2T1, D/300SC-E1D/300SC-2E1 or D/600SC-2E1 time slot. The function can operate in either thesynchronous (blocking) or asynchronous (non-blocking) mode.


devh: Specifies the valid time slot device handle returned by acall to dt_open( ). The specified time slot must be in theoffhook, idle state when dt_dial( ) is called.

digstr: Pointer to the ASCIIZ string of digits to dial. Themaximum length of the string is 32 digits.

tmo: Specifies the maximum number of seconds that thefunction will block while awaiting a dial status responsefrom the D/xxxSC board.

Asynchronous Mode

To operate this function in asynchronous (non-blocking) mode, specify 0 for tmo.This allows the application to continue processing while awaiting a completionevent. If event handling is set up properly for your application, DTEV_PDDONEwill be returned by the sr_getevttype( ) function included in the SRL when thedial is successfully completed. See Appendix A - Standard Runtime Library forinformation on event handling.

allows the application to pulse dial dt_dial( )

81

Synchronous Mode

To operate the function in synchronous (blocking) mode, specify a length of timein seconds that the function will block for tmo. This causes the application towait for a return from the function before performing any other processing. Asuggested tmo setting for this function is 60.

! Cautions1. This function will fail under the following conditions:

• A logical board or invalid time slot device handle is specified• More than a 32 digit buffer is passed• There is insufficient memory• Signaling insertion is not enabled• The time slot is already pulse dialing• The time slot is not in the offhook idle state

2. The time slot must be in signaling insertion mode before this function iscalled. Signaling insertion mode is enabled using the dt_setsigmod( )function.

3. To use this function in asynchronous mode, you must use thedt_setevtmsk( ) and SRL sr_enbhdlr( ) functions to enable trapping thecompletion event and create an event handler to process the event. SeeAppendix A - Standard Runtime Library for more information on digitalnetwork interface event management.

4. Make sure adequate time is given to the function to complete the dial if thesynchronous mode is used.


82

! Example 1

#include <windows.h> /* For Windows applications only */ #include <srllib.h> #include <dtilib.h> #include <errno.h> /* * Basic error handler */ do_error( devh, funcname ) int devh; char *funcname; { int errorval = ATDV_LASTERR( devh ); printf( "Error while calling function %s.\n", funcname ); printf( "Error value = %d. Error message = %s.", errorval, ATDV_ERRMSGP( devh ) ); if ( errorval == EDT_SYSTEM ) { printf( "errno = %d.\n", errno ); } else { printf( "\n" ); } } main() { int tsdev; /* Time Slot device handle */ /* * Open time slot 1 on board 1 */ if ( ( tsdev = dt_open( "dtiB1T1", 0 ) ) == -1 ) { printf( "Failed to open device dtiB1T1. errno = %d\n", errno ); exit( 1 ); } /* * Set signaling mode to signaling insertion */ if ( dt_setsigmod( tsdev, DTM_SIGINS ) == -1 ) { do_error( tsdev, "dt_setsigmod()" ); exit( 1 ); } /* * Disable silence transmission */ if ( dt_setidle( tsdev, DTIS_DISABLE ) == -1 ) { do_error( tsdev, "dt_setidle()" ); exit( 1 ); } /* * Go offhook */ if ( dt_settssig( tsdev, DTB_ABIT | DTB_BBIT, DTA_SETMSK ) == -1 ) { do_error( tsdev, "dt_settssig()" ); exit( 1 ); } /* * Dial number with 60 second timeout. Note that this is the blocking * mode dial. */ if ( dt_dial( tsdev, "7223689", 60 ) == -1 ) { do_error( tsdev, "dt_dial()" ); exit( 1 );

allows the application to pulse dial dt_dial( )

83

} /* * Continue processing * . * . */ /* * Done processing - close device. */ if ( dt_close( tsdev ) == -1 ) { do_error( tsdev, "dt_close()" ); } }

! Example 2 � Setting Flash Hook Using dt_dial( )

/* * Set flash hook */

setflashhook(tsdev) { char dial_str[10]; int value; sprintf(dial_str, "%c", DTV_FLASHCHR); tmo = 10; dt_dial(tsdev, string, tmo);

/* * Change flash time */ value = 100; /* 1 sec */ . . . dt_setparm(tsdev, DTG_PDDLFTIM, (void *)&value); }


84

! Errors

If the function returns -1, use the SRL Standard Attribute functionATDV_LASTERR( ) to obtain the error code. See Appendix A - StandardRuntime Library for more information on SRL functions. The error codesreturned by ATDV_LASTERR are:

• EDT_BADBRDERR - Digital network interface missing or defective• EDT_BADCMDERR - invalid or undefined command to driver• EDT_DATTO - data reception timed out• EDT_FWERR - firmware returned an error• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_PARAMERR - invalid parameter• EDT_RANGEERR - bad/overlapping physical memory range• EDT_SIZERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - system error - check the global variable errno for more

information about the error• EDT_TMOERR - timed out waiting for reply from firmware• EDT_INVTS - invalid time slot device handle• EDT_SIGINS - signaling insertion not enabled• EDT_TSBSY - time slot is busy• EDT_PDOFFHK - not in offhook idle state• EDT_PDSIG - cannot disable insertion when pulse dialing


! See Also

In Voice API Library Reference (for Linux or Windows):

• dx_dial( )

returns information about the digital network interface dt_getctinfo( )

85

Name: int dt_getctinfo(devh,ct_devinfop) Inputs: int devh • digital network interface

device time slot handle CT_DEVINFO *ct_devinfop • pointer to device

information structure Returns: 0 on success


dtilib.hctinfo.h

Category: SCbus Routing Mode: synchronous

! Description

The dt_getctinfo( ) function returns information about the digital networkinterface device associated with the specified digital channel (time slot) (dtiBxTx)on a DTI or voice and network board.


devh: Specifies the valid digital network interface timeslot device handle returned by a call todt_open( ).

ct_devinfop: Specifies the pointer to the data structureCT_DEVINFO.

On return from the function, the CT_DEVINFO structure contains the relevantinformation and is declared as follows:

typedef struct { unsigned long ct_prodid; /* product ID */ unsigned char ct_devfamily; /* device family */ unsigned char ct_devmode; /* device mode */ unsigned char ct_nettype; /* network interface */ unsigned char ct_busmode; /* bus architecture */ unsigned char ct_busencoding; /* bus encoding */ union { unsigned char ct_RFU[7]; /* reserved */ struct { unsigned char ct_protttype; } ct_net_devinfo; } ct_ext_devinfo; } CT_DEVINFO;

dt_getctinfo( ) returns information about the digital network interface

86

Valid values for each member of the CT_DEVINFO structure are defined inctinfo.h. Possible return values are:

ct_prodid: field contains a valid product identification number for the device.

ct_devfamily: specifies the device family and contains• CT_DFSPAN - specifies a T1 or E1 digital interface device

ct_devmode: not valid for T1 or E1 devices

ct_nettype: specifies the type of network interface for the device. The two validvalues are:• CT_NTT1 - specifies a T1 digital channel• CT_NTE1 - specifies a E1 digital channel

ct_busmode: specifies the bus architecture used to communicate with otherdevices in the system. The two valid values are:• CT_BMSCBUS - specifies SCbus architecture• CT_BMH100 - specifies H.100 or CT Bus architecture

ct_ext_devinfo.ct_net_devinfo.ct_prottype: contains information about theprotocol used on the specified digital network interface device. The followingvalues are currently supported:• CT_ISDN• CT_CAS• CT_R2MF• CT_CLEAR

! Cautions

This function will fail if an invalid time slot device handle is specified.

returns information about the digital network interface dt_getctinfo( )

87

! Example


main( ) {

int devh; /* Digital network interface device handle */ CT_DEVINFO ct_devinfo; /* Device information structure */

/* Open board 1 time slot 1 on Digital network interface device */ if ((devh = dt_open("dtiB1T1", 0)) == -1) { printf("Cannot open time slot dtiB1T1. errno = %d", errno); exit(1); }

/* Get Device Information */ if (dt_getctinfo(devh, &ct_devinfo) == -1) { printf("Error message = %s", ATDV_ERRMSGP(devh)); exit(1); }

printf("%s Product Id = 0x%x, Family = %d, Network = %d, Bus mode = %d, Encoding = %d", ATDV_NAMEP(devh), ct_devinfo.ct_prodid, ct_devinfo.ct_devfamily, ct_devinfo.ct_nettype, ct_devinfo.ct_busmode, ct_devinfo.ct_busencoding); }

dt_getctinfo( ) returns information about the digital network interface

88

! Errors

If the function returns -1, use the SRL Standard Attribute functionATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) toobtain a descriptive error message. The error codes returned byATDV_LASTERR( ) are:

• EDT_BADBRDERR - Board missing or defective• EDT_BADCMDERR - Invalid command parameter to driver• EDT_FWERR - Firmware returned an error• EDT_INVTS - Invalid time slot device handle• EDT_INVMSG - Invalid message• EDT_SH_BADLCLTS - Invalid local time slot number• EDT_SH_BADINDX - Invalid Switch Handler library index number• EDT_SH_BADTYPE - Invalid local time slot type• EDT_SH_LIBBSY - Switch Handler library busy• EDT_SH_LIBNOTINIT - Switch Handler library is uninitialized• EDT_SH_MISSING - Switch Handler is not present• EDT_SH_NOCLK - Switch Handler clock fallback failed• EDT_SYSTEM - system error• EDT_TMOERR - Timed out waiting for reply from firmware

! See Also

In the SCbus Routing Function Reference:

• ag_getctinfo( )• dx_getctinfo( )

blocks and returns control to the program dt_getevt( )

89

Name: int dt_getevt(devh,eblkp,timeout) (Windows only) Inputs: int devh • D/240SC-T1 or D/300SC-E1

Digital network interface devicetime slot handle

EV_EBLK *eblkp • pointer to Event Block Structure int timeout • timeout value in seconds

Returns: 0 on success -1 on failure

Includes: srllib.h dtilib.h

Category: Parameter Request Mode: Synchronous

! Description

This dt_getevt( ) function blocks and returns control to the program after one ofthe events set by dt_setevtmsk( ) occurs on the channel specified in the devhparameter, or a timeout occurs. dt_getevt( ) is used with multi-threadedapplications only.


devh: Specifies the valid digital network interface time slot devicehandle returned by a call to dt_open( )

*eblkp: Points to the Event Block Structure DX_EBLK, which willcontain the event that ended the blocking

timeout: Specifies the maximum amount of time in seconds to waitfor an event to occur. timeout can have one of thefollowing values:• # of seconds: maximum length of time to wait for an

event. - when time has elapsed, the function will terminateand return an error

• -1: block until an event occurs - the function will nottimeout

• 0: returns -1 immediately if no event is present

dt_getevt( ) blocks and returns control to the program

90

NOTE: When the time specified expires, dt_getevt( ) will terminate and returnan error. The Standard Attribute function ATDV_LASTERR( ) can beused to determine the cause of the error, which in this case isEDX_TIMEOUT.

On successful return from the function the event block structure will have thefollowing information.eblk.ev_dev: Device on which the event occurred - this will be

the same as the devh parameter passed in.eblk.ev_event: DTEV_SIG indicates signaling transition event.

DTEV_T1ERRC indicates alarm.eblk.ev_data[ ]: DTEV_SIG contains information about the

signaling event. ev_data[ ] is an array of byteswhere ev_data[0] and ev_data[1] contain thesignaling information. Retrieve the signalinginformation in a short variable and see the examplebelow to get the signaling information fromev_data[0] and ev_data[1]. DTEV_T1ERRCcontains information about the type of alarmoccurring.

The event block structure is defined as follows:

typedef struct ev_eblk { long ev_dev; /* Device on which event occurred */ unsigned long ev_event; /* Event type */ long ev_len; /* Length of data associated with event */ char ev_data[8]; /* 8 byte data buffer */ void * ev_datap; /* Variable pointer if more than 8 bytes of data */} EV_EBLK;

! Cautions

dt_getevt( ) is only used for multithreaded applications.

blocks and returns control to the program dt_getevt( )

91

! Example

#include <windows.h> #include <srllib.h> #include <dtilib.h> #include <errno.h>

EV_EBLK eblk; main() { int devh; /* Board device handle */ unsigned short bitmaskp; /* Bitmask variable */ unsigned short sigmsk = DTMM_AON | DTMM_AOFF | DTMM_BON | DTMM_BOFF; short sig, indx;

/* * Open Timeslot 1 device */ if ( ( devh = dt_open( "dtiB1T1", 0 ) ) == -1 ) { printf( "Cannot open timeslot dtiB1T1. errno = %d", errno ); exit( 1 ); } if (dt_setevtmsk(ddd, DTG_SIGEVT, sigmsk, DTA_SETMSK) == -1) { printf("%s: dt_setevtmsk DTG_SIGEVT DTA_SETMSK ERROR %d: %s: Mask = 0x%x\n",ATDV_NAMEP(ddd),ATDV_LASTERR(ddd),ATDV_ERRMSGP(ddd),sigmsk); dt_close(ddd); exit(1); } /* * Wait for events on this timeslot */ while(1) { dt_getevt ( devh, &eblk, -1 ); /* Wait for ever */ sig = eblk.ev_data[0] | ( (short) eblk.ev_data[1] << 8 );

for (indx = 0; indx <4; indx++) { if (!(sig & (0x1010 << indx))) { continue; } switch (sig & (0x1111 << indx)) { case DTMM_AOFF: fprintf(stderr,"A-OFF "); break;

case DTMM_AON: fprintf(stderr,"A-ON "); break; case DTMM_BOFF: fprintf(stderr,"B-OFF "); break; case DTMM_BON: fprintf(stderr,"B-ON "); break; } /* End of switch Statement */ } /* end of for statement */ } /* end of while statement */ . . . }

dt_getevt( ) blocks and returns control to the program

92

! Errors

If the function returns -1, use the SRL Standard Attribute functionATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) toobtain a descriptive error message. The error codes returned byATDV_LASTERR( ) are: Equate Returned When

EDT_BADPARM Invalid parameter EDT_SYSTEM Windows system error EDT_TMOERR Timed out waiting for reply from firmware

! See Also• dt_getevtmsk( )

retrieves the current event bitmask(s) dt_getevtmsk( )

93

Name: int dt_getevtmsk(devh,event,bitmaskp) Inputs: int devh • digital network interface

logical board or digital networkinterface logical time slotdevice handle

int event • event to retrieve unsigned short *bitmaskp • pointer to bitmask variable



Category: Parameter Request Mode: synchronous

! Description

The dt_getevtmsk( ) function retrieves the current event bitmask(s) for thespecified event type and digital network interface logical board or time slotdevice. The function can be used to find which bitmask was set by thedt_setevtmsk( ) function.


devh: Specifies the valid digital network interface logical board ordigital network interface logical time slot device handle returnedby a call to dt_open( ).

event: Specifies which event�s bitmask will be retrieved. The possiblevalues for event are:

• DTG_T1ERREVT - get T1 error bitmask (board level event) • DTG_E1ERREVT - get E1 error bitmask (board level event) • DTG_SIGEVT - get signaling bitmask (time slot event) • DTG_PDIGEVT - determine if pulse digit detection is

enabled or disabled for the selected time slot deviceSee Table 5 for the mask values returned

bitmaskp: Points to the variable that will contain the value of the bitmask

dt_getevtmsk( ) retrieves the current event bitmask(s)

94

Table 5. dt_getevtmsk( ) Return Values

Event Return Description

DTG_T1ERREVT DTEC_LOS loss of T1 digital signal maskDTEC_DPM driver performance monitor maskDTEC_RED receive red alarm maskDTEC_BPVS bipolar violation count saturation

maskDTEC_ECS error count saturation maskDTEC_RYEL receive yellow alarm maskDTEC_RCLX receive carrier loss maskDTEC_FERR frame bit error maskDTEC_B8ZSD bipolar 8 zero substitution detect

maskDTEC_RBL receive blue alarm maskDTEC_RLOS receive loss of sync maskDTEC_OOF out of frame error mask

DTG_E1ERREVT DEEC_RLOS receive loss of sync maskDEEC_RUA1 receive unframed all ones alarm

maskDEEC_FSERR frame sync error maskDEEC_RRA receive remote alarm maskDEEC_BPVS bipolar violation count saturation

maskDEEC_CECS CRC error count saturation maskDEEC_ECS error count saturation maskDEEC_LOS loss of E1 digital signal detected

maskDEEC_DPM driver performance monitor maskDEEC_MFSERR multiframe sync error maskDEEC_RSA1 receive signaling all ones alarm maskDEEC_RDMA receive distant multiframe alarm

mask


95

Event Return Description

DTG_SIGEVT DTMM_AON signaling bit �A� ON event maskDTMM_AOFF signaling bit �A� OFF event maskDTMM_BON signaling bit �B� ON event maskDTMM_BOFF signaling bit �B� OFF event maskDTMM_WINK receive wink signaling event mask

(E1 only) DTMM_CON signaling bit �C� ON event mask" " DTMM_COFF signaling bit �C� OFF event mask" " DTMM_DON signaling bit �D� ON event mask" " DTMM_DOFF signaling bit �D� OFF event maskDTG_PDIGEVT DTIS_ENABLE pulse digit detection enabled

DTIS_DISABLE pulse digit detection disabled

NOTE: When the DTG_T1ERREVT, DTG_E1ERREVT, DTG_SIGEVT, orDTG_PDIGEVT event is generated, call the sr_getevtdatap( ) functionin the event handler to get a pointer to the event value. The pointershould be cast to an unsigned short pointer and the event retrieved as anunsigned short value.

Refer to Appendix A - Standard Runtime Library for more information on SRLdata structures and functions.

dt_getevtmsk( ) retrieves the current event bitmask(s)

96

! Cautions

This function will fail under the following conditions:

• The board or time slot device handle is invalid• The event field is invalid

! Example


main() { int devh; /* Board device handle */ unsigned short bitmaskp; /* Bitmask variable */


/* * Get current T1 error mask */ if ( dt_getevtmsk( devh, DTG_T1ERREVT, &bitmaskp ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); }

/* * Check for loss of T-1 digital signal */ if ( bitmaskp & DTEC_LOS) { printf( "Loss of T-1 digital signal will be reported \n"); } . . }


97

! Errors

If the function returns -1, use the SRL Standard Attribute functionATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) toobtain a descriptive error message. See Appendix A - Standard Runtime Libraryfor more information on SRL functions. The error codes returned byATDV_LASTERR( ) are:

• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid or undefined command to driver• EDT_DATTO - data reception timed out• EDT_FWERR - firmware returned an error• EDT_INVBD - invalid digital network interface logical board device handle• EDT_INVTS - invalid digital network interface logical time slot device

handle• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_PARAMERR - invalid parameter• EDT_RANGEERR - bad/overlapping physical memory range• EDT_SIZERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - system error - check the global variable errno for more



! See Also

• dt_setevtmsk( )• sr_enbhdlr( )• sr_dishdlr( )

dt_getparm( ) gets the current value

98

Name: int dt_getparm(devh,param,valuep) Inputs: int devh • digital network interface

logical board device handle unsigned long param • device parameter defined name void *valuep • pointer to integer variable for

parameter value Returns: 0 on success


dtilib.h Category: Parameter Request

Mode: synchronous

! Description

The dt_getparm( ) function gets the current value of the selected digital networkinterface device parameter.


devh: Specifies the valid digital network interface logical boarddevice handle returned by a call to dt_open( ).

param: Specifies the parameter to be examined. valuep: Points to the variable to which the value of the parameter

will be assigned.

Table 6 lists each parameter name, its default value, and a brief description.

Table 6. dt_getparm( ) Parameters

#DEFINE VALUE DESCRIPTION

DTG_RDEBON 0-255 (5 default) debounce value for receivesignaling transitions from logical 0to 1 and 1 to 0 (in 10 ms units).DTG_RDEBON is used for onlythe debounce on value for DTI/1xxboards, but is used for bothdebounce on and debounce off fordigital network interface boards.

gets the current value dt_getparm( )

99


DTG_CABTYPE - - - line interface unit (LIU) cablelength and type (T1 only):

Digital Network Interface only DTLL_G703 CCITT recommendation G.703,

2.048 MHz DTLL_FCC68 FCC part 68 option A, CSU DTLL_ANSIT1 ANSI T1.403, CSU DTLL_133ABAM 0-133 feet DSX-1 ABAM (default) DTLL_266ABAM 133-266 feet DSX-1 ABAM DTLL_399ABAM 266-399 feet DSX-1 ABAM DTLL_533ABAM 399-533 feet DSX-1 ABAM DTLL_655ABAM 533-655 feet DSX-1 ABAM D/240SC-T1 only DTLL_000 000-110 feet DTLL_110 110-220 feet DTLL_220 220-330 feet DTLL_330 330-440 feet DTLL_440 440-550 feet DTLL_550 550-655 feet DTLL_655 655 feet or greater DTLL_SQUARE square pulse DTG_CODESUPR - - - bipolar format suppression value

(T1 only) DTSP_TRAN transparent (default) DTSP_B8ZS binary 8 zero suppression DTSP_BIT7 bit 7 stuffing DTG_IDLTYP - - - gets IDLE value.

NOTE: The return value will be0x00 if idle was disabled duringboard download.


100


IDLE_7F (T1default if idle isenabled)

T1 IDLE value is 7FH

IDLE_54 (E1default if idle isenabled)

E1 IDLE value is 54H

IDLE_FF T1 IDLE value is FFH IDLE_D5 E1 IDLE value is D5H DTG_SETBDMD - - - get device mode value. This

parameter will NOT change thedevice mode if the digital networkinterface remote loopback testswitch is set to ON.

DTMD_NORMAL normal mode (default if digitalnetwork interface remote loopbacktest switch is set to OFF)

DTMD_XCVRLB transceiver local loopback mode(used for digital network interfacetesting)

DTMD_LIULLB line interface unit local loopbackmode (used for digital networkinterface testing)

DTMD_LIURLB line interface unit remote loopbackmode (used by network for networktesting)

DTG_SETCLK - - - get clock source (see the SoftwareInstallation Guide)

DTC_LOOP(default)

loop timing (clock derived fromreceive sync; if RLOS detected,falls back to DTC_IND)

DTC_IND 1.544 MHz (T1) or 2.048 MHz(E1) independent timing

DTC_NOCLK no clock


101


DTG_OOFMAX 0-15 (0 default) (T1 only) number of out-of-frameerrors to allow before sending analarm (maximum <= 15). For thedefault value, an alarm is sent afterfirst detected frame error

DTG_ECRRSTTM 10 (default) (E1 only) rate, in 100 ms units, toreset the following 3 error-countregisters

DTG_BPVCMAX 0 - 255 (255default)

bipolar violation count saturation

DTG_CECRMAX 0 - 255 (255default)

(E1 only) CRC error countsaturation

DTG_FECRMAX 0 - 255 (4 default) (E1 only) frame sync error countsaturation Caution: Do not use this parameterin T1 applications.

DTG_FECSMAX 0 (default) (T1 only) frame error countsaturation. Caution: Do not use this parameterin E1 applications.

DTG_PREWINK 0 (default) pre-wink transmit delay in 10 msunits.

DTG_WINKLEN 15 (default) transmit wink duration in 10 msunits.

DTG_WINKMIN 10 (default) minimum receive wink time in 10ms units.

DTG_WINKMAX 32 (default) maximum receive wink time in 10ms units.


102

#DEFINE VALUE DESCRIPTION DTG_RXTXIDLE 0x0F0E (E1

default) 0x0C00 (T1default)

used to set the receive and transmitidle patterns that must be presentprior to waiting for a seizure. Theupper byte represents the receivesignaling pattern, and the lowerbyte represents the transmitsignaling pattern. Bits 0 to 3represent transmit A, B, C, and Dbits. Bits 8 to 11 represent receiveA, B, C, and D bits. OFF=0 andON=1.

DTG_SEIZESIG 0x0C0F (E1default) 0x0D01 (T1default)

used to set the receive signalingpattern that defines a line seizureand the transmit signaling patternto use for a response. Bits 0 to 3represent transmit A, B, C, and Dbits. Bits 8 to 11 represent receiveA, B, C, and D bits. OFF=0 andON=1.


103


• An invalid digital network interface logical board device handle isspecified

• The parameter specified is invalid

2. This function will not fail if time slot devices are open on the digital networkinterface logical board device.

3. The value of the parameter returned by this function is an integer. Thevaluep pointer is the address of an integer, but should be cast as a voidpointer when passed in the parameter field.

! Example


main() { int devh; /* Board device handle */ int valuep; /* Parameter value */ /* * Open board 1 device */ if ( ( devh = dt_open( "dtiB1", 0 ) ) == -1 ) { printf( "Cannot open board dtiB1. errno = %d", errno ); exit( 1 ); }

/* * Get current clock parameter value */ if ( dt_getparm( devh, DTG_SETCLK, ( void * )&valuep ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); }

/* * Report current clock setting */ if ( valuep & DTC_LOOP) { printf( "Clock is set to loop timing \n"); } . }


104

! Errors


• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid or undefined command to driver• EDT_BADGLOB - invalid param value• EDT_FWERR - firmware returned an error• EDT_INVBD - invalid digital network interface logical board device handle• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_PARAMERR - invalid parameter• EDT_RANGEERR - bad/overlapping physical memory range• EDT_SIZERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - system error - check the global variable errno for more



! See Also

• dt_setparm( )

returns the SCbus time slot dt_getxmitslot( )

105

Name: int dt_getxmitslot(devh,sc_tsinfop) Inputs: int devh • digital network interface

device time slot SC_TSINFO *sc_tsinfop • pointer to SCbus time slot


-1 if error Includes: srllib.h

dtilib.h Category: SCbus Routing

Mode: synchronous

! Description

The dt_getxmitslot( ) function returns the SCbus time slot connected to thetransmit of a digital network interface device time slot.

NOTE: The SCbus convenience function nr_scroute( ) includesdt_getxmitslot( ) functionality; see the Voice Programmer�s Guide.


devh: Specifies the valid digital network interface time slotdevice handle returned by a call to dt_open( )

sc_tsinfop: Specifies the pointer to the data structure SC_TSINFO

The sc_numts member of the SC_TSINFO structure must be initialized with thenumber of SCbus time slots requested (1 for a digital network interface devicetime slot). The sc_tsarrayp member of the SC_TSINFO structure must beinitialized with a pointer to a valid array. Upon return from the function, thearray will contain the number (between 0 and 1023) of the SCbus time slot onwhich the digital network interface device time slot transmits. The SC_TSINFOstructure is declared as follows:

dt_getxmitslot( ) returns the SCbus time slot

106

typedef struct { unsigned long sc_numts; long *sc_tsarrayp; } SC_TSINFO;

A digital network interface device time slot can transmit on only one SCbus timeslot.

! Cautions

This function will fail when an invalid time slot device handle is specified.

! Example


main( ) { int devh; /* Time slot device handle */ SC_TSINFO sc_tsinfo; /* Time slot information structure */ long scts; /* SCbus time slot */

/* Open board 1 time slot 1 for Digital network interface device */ if ((devh = dt_open("dtiB1T1", 0)) == -1) { printf("Cannot open time slot dtiB1T1. errno = %d", errno); exit(1); }

/* Fill in the SCbus time slot information */ sc_tsinfo.sc_numts = 1; sc_tsinfo.sc_tsarrayp = &scts;

/* Get SCbus time slot connected to transmit of time slot (digital channel) 1 on board 1 */ if (dt_getxmitslot(devh, &sc_tsinfo) == -1) { printf("Error message = %s", ATDV_ERRMSGP(devh)); exit(1); }

printf("%s is transmitting on SCbus time slot %d", ATDV_NAMEP(devh), scts); }

returns the SCbus time slot dt_getxmitslot( )

107

! Errors


• EDT_BADBRDERR - Board missing or defective• EDT_BADCMDERR - Invalid command parameter to driver• EDT_FWERR - Firmware returned an error• EDT_INVTS - Invalid time slot device handle• EDT_INVMSG - Invalid message• EDT_SH_BADLCLTS - Invalid local time slot number• EDT_SH_BADINDX - Invalid Switch Handler library index number• EDT_SH_BADMODE - Invalid Switch Handler bus configuration• EDT_SH_BADTYPE - Invalid local time slot type• EDT_SH_LCLDSCNCT - Local time slot is already disconnected from the

SCbus• EDT_SH_LIBBSY - Switch Handler library busy• EDT_SH_LIBNOTINIT - Switch Handler library is uninitialized• EDT_SH_MISSING - Switch Handler is not present• EDT_SH_NOCLK - Switch Handler clock fallback failed• EDT_SYSTEM - system error• EDT_TMOERR - Timed out waiting for reply from firmware

! See Also


• ag_listen( )• dx_listen( )

dt_listen( ) connects the digital listen channel

108

Name: int dt_listen(devh,sc_tsinfop) Inputs: int devh • digital network interface

device handle SC_TSINFO *sc_tsinfop • pointer to SCbus time slot


-1 if error Includes: srllib.h


Mode: synchronous

! Description

The dt_listen( ) function connects the digital listen channel to the SCbus timeslot. This function uses the information stored in the SC_TSINFO structure toconnect the digital receive (listen) channel (T1/E1 time slot) such as on aD/240SC-T1 or D/300SC-E1 board to an SCbus time slot. This function sets up ahalf-duplex connection. For a full-duplex connection, the receive (listen) channelof the other device must be connected to the digital transmit channel.

NOTE: The SCbus convenience function nr_scroute( ) includes dt_listen( )functionality. See the SCbus Routing Guide for more information onconvenience functions.


devh: Specifies the valid digital network interface time slotdevice handle returned by a call to dt_open( )

sc_tsinfop: Specifies the pointer to the SC_TSINFO data structure

connects the digital listen channel dt_listen( )

109

The SC_TSINFO structure is declared as follows:

typedef struct { unsigned long sc_numts; long *sc_tsarrayp;} SC_TSINFO;

The sc_numts member of the SC_TSINFO structure must be set to 1. Thesc_tsarrayp field of the SC_TSINFO structure must be initialized with a pointerto a valid array. The first element of this array must contain a valid SCbus timeslot number (between 0 and 1023) which was obtained by issuing anxx_getxmitslot( ) function (xx = ag, dt, dx or fx). Upon return from thedt_listen( ) function, the digital receive channel will be connected to this timeslot.

Although multiple SCbus device channels may listen (be connected) to the sameSCbus time slot, a digital receive (listen) channel can connect to only one SCbustime slot.

! Cautions


• An invalid device handle is specified• An invalid SCbus time slot number is specified

dt_listen( ) connects the digital listen channel

110

! Example


main( ) { int voxh; /* Voice channel device handle */ int dtih; /* Digital channel (time slot) device handle */ SC_TSINFO sc_tsinfo; /* Time slot information structure */ long scts; /* SCbus time slot */

/* Open board 1 channel 1 device */ if ((voxh = dx_open("dxxxB1C1", 0)) == -1) { printf("Cannot open channel dxxxB1C1. errno = %d", errno); exit(1); }

/* Fill in the SCbus time slot information */ sc_tsinfo.sc_numts = 1; sc_tsinfo.sc_tsarrayp = &scts;

/* Get SCbus time slot connected to transmit of channel 1 on board 1 */ if (dx_getxmitslot(voxh, &sc_tsinfo) == -1) { printf("Error message = %s", ATDV_ERRMSGP(voxh)); exit(1); }

/* Open board 1 time slot 1 on Digital network interface device */ if ((dtih = dt_open("dtiB1T1", 0)) == -1) { printf("Cannot open time slot dtiB1T1. errno = %d", errno); exit(1); }

/* Connect the receive of digital channel (time slot) 1 on board 1 to SCbus transmit time slot of voice channel 1*/ if (dt_listen(dtih, &sc_tsinfo) == -1) { printf("Error message = %s", ATDV_ERRMSGP(dtih)); exit(1); } }

connects the digital listen channel dt_listen( )

111

! Errors


• EDT_BADBRDERR - Board missing or defective• EDT_BADCMDERR - Invalid command parameter to driver• EDT_FWERR - Firmware returned an error• EDT_INVTS - Invalid time slot device handle• EDT_INVMSG - Invalid message• EDT_SH_BADLCLTS - Invalid local time slot number• EDT_SH_BADEXTTS - External time slot unsupported at current clock

rate• EDT_SH_BADINDX - Invalid Switch Handler library index number• EDT_SH_BADMODE - Invalid Switch Handler bus configuration• EDT_SH_BADTYPE - Invalid local time slot type• EDT_SH_LCLTSCNCT - Local time slot is already connected to SCbus• EDT_SH_LIBBSY - Switch Handler library busy• EDT_SH_LIBNOTINIT - Switch Handler library is uninitialized• EDT_SH_MISSING - Switch Handler is not present• EDT_SH_NOCLK - Switch Handler clock fallback failed• EDT_SYSTEM - system error• EDT_TMOERR - Timed out waiting for reply from firmware

! See Also


• dt_unlisten( )• ag_getxmitslot( )• dx_getxmitslot( )

dt_open( ) opens a digital network interface device

112

Name: int dt_open(name,oflags) Inputs: char *name • digital network interface

logical board or time slotdevice name

int oflags • open attribute flags; reservedfor future use

Returns: device handle if successful-1 on failure


Category: Resource Management Mode: synchronous

! Description

The dt_open( ) function opens a digital network interface device and returns aunique handle to identify the device. All subsequent references to the openeddevice must use the returned device handle.

All digital network interface logical boards and time slot devices can be openedwith this function. Opening a digital network interface device does not alter thestate of the device. Opening or closing a digital network interface device doesnot affect other processes using the device but a command can only be issuedwhile the device is idle.

NOTE: If a parent process opens a device and enables events, there is noguarantee that the child process will receive a particular event. It isrecommended that you open devices in a parent process and enableevents in a child process.


name: Points to an ASCIIZ string that contains the name of a validdigital network interface logical board or time slot device.The digital network interface logical board device namesare defined in the configuration file when the SystemRelease Development Package is installed. Valid digitalnetwork interface logical board and time slot device namesare usually found in the /dev directory.

opens a digital network interface device dt_open( )

113


To avoid conflict between the DTI/ driver and the genericdriver, follow the guidelines below when defining devicesin the configuration files:The name of the D/xxxSC device defined in/usr/dialogic/cfg/.voxcfg may be in the form dtiBx, dtiBx,dtiBxTy, or dtiBxTy where:• x is the logical board device number (e.g. 1, 2, 3, ...)

• y is the time slot number beginning with 1 (e.g. 1, 2, .. 24)

NOTE: The devices are named dtiBx and dtiBxTy by default, but may benamed dtiBx or dtiBxTy to allow backwards compatibility forpreviously designed applications.

oflags: Reserved for future use. Set this parameter to 0.


• The device name is not valid• The device is already open• The system has insufficient memory to complete the open

2. For T1 systems, time slot number must be in the range of 1 to 24.

3. For E1 systems, time slot number must be in the range of 1 to 30.

4. Devices should never be opened using the open( ) function.

dt_open( ) opens a digital network interface device

114

! Example



/* * Open board 1 device */ if ( ( devh = dt_open( "dtiB1", 0 ) ) == -1 ) { printf( "Cannot open board dtiB1. errno = %d", errno ); exit( 1 ); } . . . }

! Errors

The dt_open( ) function does not return errors in the standard digital networkinterface return code format because it is a system error. If an error occurs duringthe dt_open( ) call, a -1 will be returned and the specific error message will bereturned in the errno global variable. If a call to dt_open( ) is successful, thereturn value is a valid handle for the open device.

! See Also

• dt_close( )

runs diagnostics dt_rundiag( )

115

Name: int dt_rundiag(devh,tmo,diagbufp) Inputs: int devh • digital network interface

logical board device handle int tmo • timeout value char *diagbufp • pointer to 1-byte buffer for

diagnostic code Returns: 0 on success


dtilib.h Category: Diagnostic

Mode: synchronous/asynchronous

! Description

The dt_rundiag( ) function runs diagnostics on the Network firmware. Thefunction can operate in synchronous (blocking) or asynchronous (non-blocking)mode.

Please note the following guidelines when using this function:

• This function can be issued at any time, but it is recommended that all timeslots be idle and closed.

• This function is destructive to calls in progress.• The board will be restored to its previous state; that is, the state the board

was in before the function was called.• The function should take about 5 seconds to complete.


devh: Specifies the valid digital network interface board devicehandle returned by a call to dt_open( )

tmo: When operating the function in synchronous mode,specifies the length of time in seconds the function willblock while waiting for a response from the device

diagbufp: Pointer to a one-byte data buffer to which the diagnosticcode will be returned when the function is operating insynchronous mode

dt_rundiag( ) runs diagnostics

116

Synchronous Mode

To operate the function in synchronous (blocking) mode, specify in tmo thelength of time in seconds that the function will block. This causes the applicationto await a return from the function before performing any other processing. Asuggested setting for tmo is 5.

Asynchronous Mode

To operate the function in asynchronous (non-blocking) mode, set tmo to 0. Thisallows the application to continue processing while awaiting a completion eventfrom the device.

If event handling is set up properly for your application, DTEV_RETDIAG isreturned by the SRL sr_getevttype( ) function when the diagnostics aresuccessfully completed.

To use this function in asynchronous mode, you must use the SRL sr_enbhdlr( )function to enable trapping of the event and create an event handler to process thecompletion event returned by the device. See Appendix A - Standard RuntimeLibrary for more information on digital network interface event management.

NOTE: To run this function in asynchronous operation, you must pass a NULLpointer to diagbufp.

Diagnostic Return Codes

The diagnostic codes listed below provide results of the diagnostics run on thedigital network interface firmware. In synchronous mode, the diagnostic codesare returned to the one-byte buffer pointed to by diagbufp. In asynchronousmode, the codes are returned by the SRL sr_getevtdatap( ) function.

• D2DE_BRDCFG - Invalid board configuration data• D2DE_INVEE - Invalid EEPROM data (not valid for D/240SC-T1)• D2DE_LIUFAIL - Read/write to LIU failed• D2DE_MEMTST - Memory test failed• D2DE_NOERR - No errors• D2DE_ROMCHK - Bad ROM checksum (not valid for D/240SC-T1)• D2DE_XCVRFAIL - Read XCVR register failed


117


• An invalid digital network interface logical board device handle isspecified

• There is a firmware/hardware problem on the device

2. Make sure all time slots are closed and idle. This function is destructive tocalls in progress.

dt_rundiag( ) runs diagnostics

118

! Example


main() { int devh; /* Board device handle */ int retval; /* Return value from function call */ char diagbufp; /* Diagnostic buffer */ /* * Open board 1 device */

if ( ( devh = dt_open( "dtiB1", 0 ) ) == -1 ) { printf( "Cannot open board dtiB1. errno = %d", errno ); exit( 1 ); } /* * Run diagnostics on the board with a 5 second timeout. */ if ( ( retval = dt_rundiag( devh, 5, &diagbufp ) ) == -1 ) { printf("Error activating diag tests: error message = %s\n", ATDV_ERRMSGP( devh ) ); } if ( diagbufp ! = DTDE_NOERR ) printf( "Diagnostic buffer value = %d\n", diagbufp ); exit( 1 ); } . . . }


119

! Errors


• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid or undefined command to driver• EDT_DATTO - data reception timed out• EDT_FWERR - firmware returned an error• EDT_INVBD - invalid digital network interface logical board device handle• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_PARAMERR - invalid parameter• EDT_RANGEERR - bad/overlapping physical memory range• EDT_SIZEERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - indicates system error - look at global variable errno for

actual error• EDT_TMOERR - timed out waiting for reply from firmware


! See Also

• dt_tstcom( )• dt_tstdat( )

dt_setevtmsk( ) enables and disables notification for events

120

Name: dt_setevtmsk(devh,event,bitmask,action) Inputs: int devh • digital network interface

logical board or digitalnetwork interface logical timeslot device handle

int event • event to be enabled/disabled unsigned short bitmask • bitmask for events int action • set, add, or subtract bitmask



Category: Parameter Setting Mode: synchronous

! Description

The dt_setevtmsk( ) function enables and disables notification for events thatoccur on a digital network interface logical board or time slot device. Thisfunction allows the application to set and alter a bitmask of transition events. Thebitmask determines which transitions will cause an event to be generated.

The event can be retrieved by using the event management functions included inthe Standard Runtime Library (refer to Appendix A - Standard Runtime Libraryfor more information on the SRL). The current bitmask can be examined byusing the dt_getevtmsk( ) function.


devh: Specifies the valid digital network interface logical boardor digital network interface logical time slot device handlereturned by a call to dt_open( ).

event: Specifies the type of event to be enabled or disabled on thedevice specified by devh:

• DTG_T1ERREVT - T1 error events (T1-compatibledigital network interface logical board device handlesonly). Several T1 error events can be monitored.Specific T1 error events are enabled or disabled bysetting the bitmask parameter.

enables and disables notification for events dt_setevtmsk( )

121


• DTG_E1ERREVT - E1 error events (E1-compatibledigital network interface logical board device handlesonly). Several E1 error events can be monitored.Specific E1 error events are enabled or disabled bysetting the bitmask parameter.

• DTG_SIGEVT - Signaling bit transition events (timeslot device handles only). Specific signaling events areenabled or disabled by setting the bitmask parameter.

• DTG_PDIGEVT - pulse digit events (D/xxxSC timeslot device handles only).

NOTE: For D/xxxSC products, you must enable both theON and OFF transitions on a specified bit to get events onthat bit. For example, AON and AOFF must be enabled todetect events on the A bit.

bitmask: Specifies the event to be enabled or disabled by setting thebitmask for that event.

Multiple transition events may be enabled or disabled withone function call if the bitmask values are logically ORedtogether.

The bitmask values for each event parameter aredescribed in Table 5, found in the dt_getevtmsk( )function description.

action: Specifies how the signaling bit transition event mask ischanged. Events can be added to or subtracted from thosespecified in bitmask, or events can replace the existingones. The possible values for the action parameter are:

• DTA_SETMSK - enable notification of events specifiedin bitmask and disable notification of previously setevents.

• DTA_ADDMSK - enable notification of eventsspecified in bitmask in addition to previously set events.(Not valid for DTG_PDIGEVT.)

• DTA_SUBMSK - disable notification of eventsspecified in bitmask.


122

For example, to enable event notification:

1. Specify the events to enable in the bitmask field.

2. Specify the DTA_SETMSK bitmask in the action field.

This enables notification of the events specified in the bitmask parameter anddisables notification of previously set events.

To enable an additional event:

1. Specify the events in bitmask.

2. Specify DTA_ADDMSK in the action field.

This adds the notification of events specified in bitmask without disabling thecurrently enabled events.

To disable events, use the following procedure:

1. Specify the events in bitmask.

2. Specify DTA_SUBMSK in the action field.

This disables the event in bitmask without disabling any other events.

To disable all currently enabled events:

1. Specify 0 in bitmask.

2. Specify DTA_SETMSK in the action field.

Event Notification and HandlingNOTE: Event handling operations vary with the mode type (i.e., callback,

polled, synchronous, etc.) used by your application. For moreinformation on application development models, refer to the StandardRuntime Library API Programming Guide.


123

To trap and handle a specified digital network interface event, follow these stepsin the order listed:

1. Call sr_enbhdlr( ) - This function specifies the event and the applicationdefined event handler that is called when this event occurs.

2. Call dt_setevtmsk( ) - This specifies the list of events for which theapplication should be notified.

NOTE: When the DTG_T1ERREVT, DTG_E1ERREVT, or DTG_SIGEVTevent is generated, call the sr_getevtdatap( ) function in the eventhandler to get a pointer to the event value. The pointer should be cast toan unsigned short pointer and the event retrieved as an unsigned shortvalue.

Refer to Appendix A - Standard Runtime Library for more information on SRLdata structures and functions.


• An invalid time slot or an invalid digital network interface logical boarddevice handle is specified.

• The event specified is invalid.• The action specified is invalid.

2. For the application to process an event, the SRL sr_enbhdlr( ) EventManagement function should be called prior to calling the dt_setevtmsk( )function.

3. When a wink event occurs, the signaling bits associated with the wink will bereported to the application. Therefore, your application�s signaling eventhandlers must make sure that any transition of the selected wink signaling bitis not part of a wink event.


124

! Example


main() { int devh; /* Time slot device handle */ /* * Open board 1 time slot 1 device */ if ( ( devh = dt_open( "dtiB1T1", 0 ) ) == -1 ) { printf( "Cannot open device dtiB1T1. errno = %d", errno ); exit( 1 ); }

/* * Enable an event handler to catch AON and AOFF events */ . . .

/* * Enable AON and AOFF signaling transition events */ if ( dt_setevtmsk(devh, DTG_SIGEVT, DTMM_AON | DTMM_AOFF, DTA_SETMSK ) ts== -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } . . . }


125

! Errors


• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid or undefined command to driver• EDT_DATTO - data reception timed out• EDT_FWERR - firmware returned an error• EDT_INVBD - invalid digital network interface logical board device handle• EDT_INVTS - invalid digital network interface logical time slot device

handle• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_PARAMERR - invalid parameter• EDT_RANGEERR - bad/overlapping physical memory range• EDT_SIZERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - system error. Check the global variable errno for more



! See Also

• dt_getevtmsk( )• sr_enbhdlr( )• sr_dishdlr( )

dt_setidle( ) enables or disables transmission

126

Name: int dt_setidle(devh,state) Inputs: int devh • digital network interface

logical time slot device handle unsigned int state • idle state of time slot



Category: Time Slot Audio Mode: synchronous

! Description

The dt_setidle( ) function enables or disables transmission of a continuous streamof silence to the network for the audio portion of the specified time slot.Transmitting silence is referred to as �idling� or �inserting idle� on a time slot.

When two digital network interface boards are arranged in drop-and-insertconfiguration, this function can be used to disable pass-through operation.Transmitting idle overrides voice data being passed between network devices onthe selected time slot.



state: Specifies whether to enable or disable the transmission ofsilence. The possible values are:

• DTIS_DISABLE - disable idling on the time slot • DTIS_ENABLE - enable idling on the time slot

The default idle value transmitted is 7FH (T1 only) or 54H (E1 only). Werecommend you initialize the device idle value to a known state before idling atime slot. The device idle value is set using the dt_setparm( ) function with theparameter DTG_IDLTYP. The values of this parameter can be set as follows:

• IDLE_7F - sets idle value to 7FH (T1 only)• IDLE_FF - sets idle value to FFH (T1 only)• IDLE_54 - sets idle value to 54H (E1 only)

enables or disables transmission dt_setidle( )

127

• IDLE_D5 - sets idle value to D5H (E1 only)

! Cautions


• An invalid logical time slot device handle is specified• The state specified is invalid

! Example

#include <windows.h> /* For Windows applications only */ #include <srllib.h> #include <dtilib.h> #include <errno.h> main() { int devh; /* Time slot device handle */ /* * Open time slot 1 on board 1 */ if ( ( devh = dt_open( "dtiB1T1", 0 ) ) == -1 ) { printf( "Failed to open device dtiB1T1. errno = %d\n", errno ); exit( 1 ); } /* * Set signaling mode to signaling insertion */ if ( dt_setsigmod( devh, DTM_SIGINS ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } /* * Disable silence transmission */ if ( dt_setidle( devh, DTIS_DISABLE ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } /* * Go offhook */ if ( dt_settssig( devh, DTB_ABIT | DTB_BBIT, DTA_SETMSK ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } . }

dt_setidle( ) enables or disables transmission

128

! Errors


• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid or undefined command to driver• EDT_DATTO - data reception timed out• EDT_FWERR - firmware returned an error• EDT_INVTS - invalid digital network interface logical time slot device




! See Also

• ATDT_IDLEST( )• dt_setsigmod( )

changes the value of a DNI device parameter dt_setparm( )

129

Name: int dt_setparm(devh,param,valuep) Inputs: int devh • digital network interface

logical board device handle unsigned long param • device parameter defined name void* valuep • pointer to device parameter

value 0Returns: 0 on success


dtilib.h Category: Parameter Setting

Mode: synchronous

! Description

The dt_setparm( ) function changes the value of a DNI device parameter. Parameter Description


param: Specifies the parameter value to alter valuep: Specifies the address of the integer containing the value to

be assigned to the parameter

All time slots on the selected digital network interface device must be closedwhen this function is called.

Table 6, found in the dt_getparm( ) function description, lists each parametername, its default value, and a brief description.

dt_setparm( ) changes the value of a DNI device parameter

130


• An invalid digital network interface logical board device handle isspecified.

• One or more time slots on the digital network interface device are open.• The parameter specified is invalid.• The digital network interface is in test mode (remote loopback switch set

to ON) and DTG_SETBDMD is passed in the param field.

2. Changing a digital network interface device parameter affects all the timeslots on the logical board. All the time slots on a logical board must beclosed when device parameters are altered.

3. All values of the parameter have to be integers, but since this routine expectsa void pointer to valuep, the address must be cast as a void*.

! Example

#include <windows.h> /* For Windows applications only */ #include <srllib.h> #include <dtilib.h> #include <errno.h> main() { int devh; /* Board device handle */ int valuep; /* Parameter value */ /* * Open board 1 device */ if ( ( devh = dt_open( "dtiB1", 0 ) ) == -1 ) { printf( "Cannot open board dtiB1. errno = %d", errno ); exit( 1 ); } /* * Set current clock parameter value */ valuep = DTC_EXT; if ( dt_setparm( devh, DTG_SETCLK, ( void * )&valuep ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } . . . }

changes the value of a DNI device parameter dt_setparm( )

131

! Errors


• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid or undefined command to driver• EDT_BADGLOB - invalid param• EDT_BADVAL - invalid parameter value passed in valuep pointer• EDT_DATTO - data reception timed out• EDT_FWERR - firmware returned an error• EDT_INVBD - invalid digital network interface logical board device handle• EDT_NOCLK - no clock source present• EDT_NOIDLEERR - time slot not in idle/closed state• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_PARAMERR - invalid parameter• EDT_RANGEERR - bad/overlapping physical memory range• EDT_SIZERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - system error. Check the global variable errno for more

information about the error.• EDT_TMOERR - timed out waiting for reply from firmware• EDT_TSTMOD - in test mode; cannot set digital network interface mode


! See Also

• dt_getparm( )

dt_setsigmod( ) sets the type of signaling

132

Name: int dt_setsigmod(devh,mode) Inputs: int devh • digital network interface

logical time slot device handle unsigned int mode • transmit mode



Category: Time Slot Signaling Mode: synchronous

! Description

The dt_setsigmod( ) function sets the type of signaling that will be performed onthe transmitted time slot.



mode: Specifies the transmit mode. Possible values are: • DTM_SIGINS - set to signaling insertion

Signaling Insertion

When a time slot is set to signaling insertion , transmit signaling for the selectedtime slot is inserted by the digital network interface. The digital networkinterface can insert signaling information over the transmit signaling already onthat time slot.

sets the type of signaling dt_setsigmod( )

133

! Cautions


• An invalid digital network interface logical time slot device handle isspecified.

• The mode specified is invalid.

! Example


main() { int devh; /* Time slot device handle */

/* * Open time slot 1 on board 1 */ if ( ( devh = dt_open( "dtiB1T1", 0 ) ) == -1 ) { printf( "Failed to open device dtiB1T1. errno = %d\n", errno ); exit( 1 ); }

/* * Set signaling mode to signaling insertion */ if ( dt_setsigmod( devh, DTM_SIGINS ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } . . . }

dt_setsigmod( ) sets the type of signaling

134

! Errors






! See Also

• ATDT_BDMODE( )• ATDT_BDSGBIT( )• ATDT_TSMODE( )• ATDT_TSSGBIT( )• dt_settssig( )

sets or clears the transmit dt_settssig( )

135

Name: int dt_settssig(devh,bitmask,action) Inputs: int devh • digital network interface logical

time slot device handle unsigned short bitmask • signaling bits to change int action • set, add, or subtract bitmask



Category: Time Slot Signaling Mode: synchronous

! Description

The dt_settssig( ) function sets or clears the transmit for the time slot requested. Parameter Description

devh: Specifies the valid digital network interface logical time slotdevice handle returned by a call to dt_open( ).

bitmask: Specifies which signaling bits to change. All signaling bits maybe changed with one function call if the bitmask values arelogically ORed together as in the example. The possible valuesfor the bitmask parameter are:

• DTB_ABIT - �A� signaling bit • DTB_BBIT - �B� signaling bit • DTB_CBIT - �C� signaling bit (E1 only) • DTB_DBIT - �D� signaling bit (E1 only) action: Specifies whether the signaling bits in the mask should be set or

cleared (i.e., set to 1 or cleared to 0). The possible values are: • DTA_SETMSK - set bits specified in bitmask and clear all

other bits. • DTA_ADDMSK - set bits specified in bitmask. This will not

affect other bits that are currently set. • DTA_SUBMSK - clear bits in specified bitmask. This will

not affect other bits that are currently set.

dt_settssig( ) sets or clears the transmit

136

! Cautions


• An invalid digital network interface logical time slot device handle isspecified

• The action specified is invalid

! Example

#include <windows.h> /* For Windows applications only */ #include <srllib.h> #include <dtilib.h> #include <errno.h> main() { int devh; /* Time slot device handle */ /* * Open time slot 1 on board 1 */ if ( ( devh = dt_open( "dtiB1T1", 0 ) ) == -1 ) { printf( "Failed to open device dtiB1T1. errno = %d\n", errno ); exit( 1 ); } /* * Set signaling mode to signaling insertion */ if ( dt_setsigmod( devh, DTM_SIGINS ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } /* * Go offhook */ if ( dt_settssig( devh, DTB_ABIT | DTB_BBIT, DTA_SETMSK ) == -1 ) { printf( "Error message = %s.", ATDV_ERRMSGP( devh ) ); exit( 1 ); } . . . }

sets or clears the transmit dt_settssig( )

137

! Errors






! See Also

• ATDT_BDMODE( )• ATDT_BDSGBIT( )• ATDT_TSMODE( )• ATDT_TSSGBIT( )• dt_setsigmod( )

dt_settssigsim( ) simultaneous setting or clearing of transmit signaling bits

138

Name: int dt_settssigsim(devh,bitmask) Inputs: int devh • digital network interface

logical time slot device handle unsigned short bitmask • signaling bits to

simultaneously clear and set Returns: 0 on success


dtilib.h Category: Time Slot Signaling

Mode: synchronous

! Description

The dt_settssigsim( ) allows simultaneous setting or clearing of transmitsignaling bits on a digital network interface time slot. The bitmask parameterspecifies which signaling bits to change. To simultaneously set and clear thetransmit signaling bits, the chosen values can be logically ORed together.


devh: Specifies the valid digital network interface logical time slotdevice handle returned by a call to dt_open( )

bitmask: Specifies which signaling bits to change. All signaling bitsmay be changed with one function call if the bitmask valuesare logically ORed together as in the example. The possiblevalues for the bitmask parameter are:

• DTB_AON - �A� signaling bit on • DTB_AOFF - �A� signaling bit off • DTB_BON - �B� signaling bit on • DTB_BOFF - �B� signaling bit off • DTB_CON - �C� signaling bit on (E1 only) • DTB_COFF - �C� signaling bit off (E1 only) • DTB_DON - �D� signaling bit on (E1 only) • DTB_DOFF - �D� signaling bit off (E1 only) All signaling bits may be changed with one function call if

the bitmask values are ORed together

simultaneous setting or clearing of transmit signaling bits dt_settssigsim( )

139

! Cautions


! Example

#include <windows.h> /* For Windows applications only */ #include <srllib.h> #include <dtilib.h> #include <errno.h> main() { int devh; /* Time slot device handle */ /* * Open time slot 1 on board 1 */ if ( ( devh = dt_open( "dtiB1T1", 0 ) ) == -1 ) { printf( "Failed to open device dtiB1T1. errno = %d\n", errno ); exit( 1 ); } /* * Set signaling mode to signaling insertion */ if ( dt_setsigmod( devh, DTM_SIGINS ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } /* * Set A & C time slot bits while clearing the B bit simultaneously * the D bit is left untouched * / bitmask = DTB_AON | DTB_CON | DTB_BOFF; if ( dt_settssigsim( devh, bitmask) == -1) { printf( "Error message = %s.", ATDV_ERRMSGP( devh ) ); exit( 1 ); } . . . }

dt_settssigsim( ) simultaneous setting or clearing of transmit signaling bits

140

! Errors



handle• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_PARAMERR - invalid parameter• EDT_RANGEERR - bad/overlapping physical memory range• EDT_SIZERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - system error - check the global variable errno for more



! See Also

• ATDT_BDMODE( )• ATDT_BDSGBIT( )• ATDT_TSMODE( )• ATDT_TSSGBIT( )• dt_setsigmod( )

tests the ability of a digital network interface device dt_tstcom( )

141

Name: int dt_tstcom(devh,tmo) Inputs: int devh • digital network interface logical

board device handle int tmo • timeout value

Returns: digital network interface return code-1 on failure


Category: Diagnostic Mode: synchronous/asynchronous

! Description

The dt_tstcom( ) function tests the ability of a digital network interface device tocommunicate with the host PC. This function can operate in either synchronous(blocking) or asynchronous (non-blocking) mode.


• This function can be issued at any time, but it is recommended that all timeslots be idle and closed

• This function has no effect on calls in progress• This function has no effect on the state of the board



tmo: Specifies the maximum amount of time in seconds that thefunction will block while waiting for a response from thedigital network interface. If a response is not returnedwithin tmo seconds, an error is returned

Synchronous Mode

To run this function in synchronous (blocking) mode, set tmo to the length oftime, in seconds, to await a return. If a response is not returned within tmoseconds, an error is returned. A suggested tmo setting for this function is 5.

dt_tstcom( ) tests the ability of a digital network interface device

142

Asynchronous Mode

To operate this function in asynchronous (non-blocking) mode, specify 0 for tmo.This allows the application to continue processing while awaiting a completionevent. If event handling is set up properly for your application, DTEV_COMRSPwill be returned by the sr_getevttype( ) function included in the SRL when thetest is successfully completed. See Appendix A - Standard Runtime Library forinformation on event handling.

! Cautions1. This function returns a failure under the following conditions:

• The specified device fails to respond within tmo seconds, if operating insynchronous mode

• A time slot or invalid digital network interface logical device handle isspecified

• There is a hardware problem on the digital network interface• There is a configuration problem (for example, IRQ conflict)

NOTE: Device configuration information is found in the appropriatehardware installation card (see Appendix D - Related Publications).

2. To use this function in asynchronous mode, you must use the SRLsr_enbhdlr( ) function to enable trapping of events and create an eventhandler to process the completion event returned by the device.

The event can be detected by using the new event management functionsincluded in the new release of the Standard Runtime Library. See AppendixA - Standard Runtime Library for more information on digital networkinterface event management.

tests the ability of a digital network interface device dt_tstcom( )

143

! Example


main() { int devh; /* Board device handle */ /* * Open board 1 device */ if ( ( devh = dt_open( "dtiB1", 0 ) ) == -1 ) { printf( "Cannot open board dtiB1. errno = %d", errno ); exit( 1 ); }

/* * Test the board's ability to communicate with the system. Give it 5 * seconds to complete. */ if ( dt_tstcom( devh, 5 ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } . . . }

dt_tstcom( ) tests the ability of a digital network interface device

144

! Errors


• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid or undefined command to driver• EDT_DATTO - data reception timed out• EDT_FWERR - firmware returned an error• EDT_INVBD - invalid digital network interface logical board device handle• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_PARAMERR - invalid parameter• EDT_RANGEERR - bad/overlapping physical memory range• EDT_SIZERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - system error - check the global variable errno for more



! See Also

• dt_tstdat( )• dt_rundiag( )

performs a test dt_tstdat( )

145

Name: int dt_tstdat(devh,tmo) Inputs: int devh • digital network interface

logical board device handle unsigned int tmo • timeout value



Category: Diagnostic Mode: synchronous/asynchronous

! Description

The dt_tstdat( ) function performs a test that verifies the integrity of the digitalnetwork interface I/O interface to the PC. The data test is performed by sending aseries of bytes to the digital network interface and checking the integrity of thebytes returned.


• This function can be issued at any time, but it is recommended that all timeslots be idle and closed

• This function has no effect on calls in progress• This function has no effect on the state of the board



tmo: Specifies the maximum amount of time in seconds that thefunction will block while awaiting a response from thedigital network interface

Asynchronous Mode

To operate this function in asynchronous (non-blocking) mode, specify 0 for tmo.This allows the application to continue processing while awaiting a completionevent. If event handling is set up properly for your application, DTEV_DATRSPwill be returned by the sr_getevttype( ) function included in the SRL when the

dt_tstdat( ) performs a test

146

test is successfully completed. See Appendix A - Standard Runtime Library forinformation on event handling.

Synchronous Mode


! Cautions1. This function will return fail if:

• The test data is corrupted• A time slot or invalid digital network interface logical board device

handle is specified

2. To use this function in asynchronous mode, you must use the SRLsr_enbhdlr( ) function to enable trapping of events and create an eventhandler to process the completion event returned by the device. The eventcan be detected by using the SRL event management functions. SeeAppendix A - Standard Runtime Library for more information on digitalnetwork interface event management.

performs a test dt_tstdat( )

147

! Example




/* * Perform a data integrity test between the board and PC. Give it 5 * seconds to complete. */ if ( dt_tstdat( devh, 5 ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } . . . }

dt_tstdat( ) performs a test

148

! Errors


• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid or undefined command to driver• EDT_DATTO - data reception timed out• EDT_FWERR - firmware returned an error• EDT_INVBD - invalid digital network interface logical board device handle• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_PARAMERR - invalid parameter• EDT_RANGEERR - bad/overlapping physical memory range• EDT_SIZERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - system error. Check the global variable errno for more



! See Also

• dt_tstcom( )• dt_rundiag( )

disconnects the receive dt_unlisten( )

149

Name: dt_unlisten(devh) Inputs: int devh • digital network interface

device time slot Returns: 0 on success

-1 on error Includes: srllib.h


Mode: synchronous

! Description

The dt_unlisten( ) function disconnects the receive channel from the SCbus.This function disconnects the digital receive (listen) channel (T1/E1 time slot)such as on a D/240SC-T1 or D/300SC-E1 board from the SCbus time slot.

Calling the dt_listen( ) function to connect to a different SCbus time slot willautomatically break an existing connection. Therefore, when changingconnections, you need not call the dt_unlisten( ) function.

NOTE: The SCbus convenience function nr_scunroute( ) includesdt_unlisten( ) functionality; see the SCbus Routing Function Reference.


devh: Specifies a valid digital network interface time slot devicehandle returned by a call to dt_open( )

! Cautions

This function will fail if an invalid time slot device handle is specified.

dt_unlisten( ) disconnects the receive

150

! Example


main( ) { int devh; /* Digital channel (time slot) device handle */

/* Open board 1 time slot 1 device */ if ((devh = dt_open("dtiB1T1", 0)) == -1) { printf("Cannot open time slot dtiB1T1. errno = %d", errno); exit(1); }

/* Disconnect receive of board 1, time slot 1 from all SCbus time slots */ if (dt_unlisten(devh) == -1) { printf("Error message = %s", ATDV_ERRMSGP(devh)); exit(1); } }

disconnects the receive dt_unlisten( )

151

! Errors


• EDT_BADBRDERR - Board missing or defective• EDT_BADCMDERR - Invalid command parameter to driver• EDT_FWERR - Firmware returned an error• EDT_INVTS - Invalid time slot device handle• EDT_INVMSG - Invalid message• EDT_SH_BADLCLTS - Invalid local time slot number• EDT_SH_BADEXTTS - External time slot unsupported at current clock

rate• EDT_SH_BADINDX - Invalid Switch Handler library index number• EDT_SH_BADMODE - Invalid Switch Handler bus configuration• EDT_SH_BADTYPE - Invalid local time slot type• EDT_SH_LCLDSCNCT - Local time slot is already disconnected from

SCbus• EDT_SH_LIBBSY - Switch Handler library busy• EDT_SH_LIBNOTINIT - Switch Handler library is uninitialized• EDT_SH_MISSING - Switch Handler is not present• EDT_SH_NOCLK - Switch Handler clock fallback failed• EDT_SYSTEM - system error• EDT_TMOERR - Timed out waiting for reply from firmware

! See Also

• dt_listen( )

dt_xmitalrm( ) starts and stops transmission of an alarm

152

Name: int dt_xmitalrm(devh, alrmtype, state) Inputs: int devh • digital network interface

logical board device handle unsigned char alrmtype • T1 or E1 alarm type unsigned int state • enable or disable sending the

alarm Returns: 0 on success


dtilib.h Category: Alarm

Mode: synchronous

! Description

The dt_xmitalrm( ) function starts and stops transmission of an alarm to anetwork span. For a detailed description of T1 and E1 alarm handling, refer toChapter 3. Digital Telephony Overview.



alrmtype: Specifies the T1 or E1 alarm type to be transmitted • YELLOW - T1 only • BLUE - T1 only • DEA_REMOTE - E1 only • DEA_UNFRAMED1 (unframed all 1s) - E1 only • DEA_SIGNALALL1 (signaling all 1s) - E1 only • DEA_DISTANTMF (distant multiframe alarm) - E1

only state: Specifies whether to enable or disable transmission of the

specified alarm: • DTIS_DISABLE - disable transmission of alarm • DTIS_ENABLE - enable transmission of alarm

starts and stops transmission of an alarm dt_xmitalrm( )

153


• The specified digital network interface device is invalid• The specified alrmtype parameter is invalid• The specified state parameter is invalid

2. Transmission of alarms requires that the proper alarm mode is set by thedt_setalrm( ) function.

3. The alarm type transmitted must correspond to the type of network circuityou are using (either T1 or E1).

! Example

#include <windows.h> /* For Windows applications only */ #include <srllib.h> #include <dtilib.h> #include <errno.h> main() { int devh; /* Board device handle */ /* * Open board 1 device */ if ( ( devh = dt_open( "dtiB1", 0 ) ) == -1 ) { printf( "Cannot open board dtiB1. errno = %d", errno ); exit( 1 ); } /* * Transmit a BLUE alarm */ if ( dt_xmitalrm( devh, BLUE, DTIS_ENABLE ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } . . . }

dt_xmitalrm( ) starts and stops transmission of an alarm

154

! Errors


• EDT_BADBRDERR - digital network interface missing or defective• EDT_BADCMDERR - invalid or undefined command to driver• EDT_DATTO - data reception timed out• EDT_FWERR - firmware returned an error• EDT_INVBD - invalid digital network interface logical board device handle• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_PARAMERR - invalid parameter• EDT_RANGEERR - bad/overlapping physical memory range• EDT_SIZERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - system error. Check the global variable errno for more



! See Also

• dt_setalrm( )

transmits wink signaling dt_xmitwink( )

155

Name: int dt_xmitwink(devh, tmo) Inputs: int devh • digital network interface

logical time slot device handle unsigned int tmo • timeout value



Category: Time Slot Signaling Mode: synchronous/asynchronous

! Description

The dt_xmitwink( ) function transmits wink signaling to the T1 or E1 networkspan on any of the available signaling bits. The bit to be used and the polarity orbeginning state of the wink are configurable through the download parameter file(see the Installation Reference (for Linux or Windows for details). A wink startsby transmitting signaling state 0, then transmits signaling state 1, and returns tosignaling state 0. The signaling bit selected must be in the proper state (state 0)when the dt_xmitwink( ) function is called. Also, the time slot must be insignaling insertion mode to transmit a wink.

Board parameters may be set through dt_setparm( ) to control pre-wink delayand transmit wink duration for all time slots simultaneously.

NOTE: Separate board parameters are provided for setting minimum andmaximum receive wink duration. These have no effect on winktransmission.



tmo: Specifies the maximum amount of time in seconds that thefunction will block while awaiting a response from thedigital network interface

dt_xmitwink( ) transmits wink signaling

156

Asynchronous Mode

To operate this function in asynchronous (non-blocking) mode, specify 0 for tmo.This allows the application to continue processing while awaiting a completionevent from the device. If event handling is set up properly for your application,DTEV_WINKCPLT is returned by the SRL sr_getevttype( ) function when thewink is successfully completed. See Appendix A - Standard Runtime Library forinformation on event handling.

Synchronous Mode



• The specified digital network interface logical time slot device handle isinvalid

• The specified time slot is not in the correct signaling state (must begin instate 0)

• Signaling insertion is not enabled for the specified time slot device• A T1 system (e.g., D/240SC-T1 board) is configured for wink

transmission using the C bit or D bit• An application attempts to change signaling mode or signaling bits while

wink transmission is in progress

2. To use this function in asynchronous mode, you must use the SRLsr_enbhdlr( ) function to enable trapping of events and create an eventhandler to process the completion event returned by the device. The eventcan be detected by using the SRL event management functions. SeeAppendix A - Standard Runtime Library for more information on digitalnetwork interface event management.

transmits wink signaling dt_xmitwink( )

157

! Example

#include <windows.h> /* For Windows applications only */ #include <srllib.h> #include <dtilib.h> #include <errno.h> main() { int devh; /* Time slot device handle */ /* * Open time slot 1 on board 1 */ if ( ( devh = dt_open( "dtiB1T1", 0 ) ) == -1 ) { printf( "Failed to open device dtiB1T1. errno = %d\n", errno ); exit( 1 ); } /* * Set signaling bits to a known state */ if ( dt_settsig ( devh, DTB_ABIT | DTB_BBIT, DTA_SUBMSK ) == -1 ) { printf( "Error message = %s \n", ATDV_ERRMSGP( devh ) ); exit( 1 ); } /* * Set signaling mode to signaling insertion */ if ( dt_setsigmod( devh, DTM_SIGINS ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } * * Disable silence transmission */ if ( dt_setidle( devh, DTIS_DISABLE) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } /* * Go offhook assuming that wink set to negative polarity on A bit */ if ( dt_settssig( devh, DTB_ABIT, DTA_SETMSK ) == -1 ) { printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } /* * Transmit wink with 2 second timeout. Note that this is the blocking * (synchronous) mode */

if ( dt_xmitwink( devh, 2 ) == -1 ) {

printf( "Error message = %s.",ATDV_ERRMSGP( devh ) ); exit( 1 ); } . . . }

dt_xmitwink( ) transmits wink signaling

158

! Errors

If the function returns -1, use the SRL Standard Attribute functionATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) toobtain a descriptive error message (see Appendix A - Standard Runtime Libraryfor more information). The error codes returned by ATDV_LASTERR( ) are:


handle• EDT_NOMEMERR - cannot map or allocate memory in driver• EDT_PARAMERR - invalid parameter• EDT_PDOFFHK - wink bit not in correct initial state• EDT_RANGEERR - bad/overlapping physical memory range• EDT_SIGINS - signaling insertion not enabled• EDT_SIZERR - message too big or too small• EDT_SKIPRPLYERR - a required reply was skipped• EDT_SYSTEM - system error. Check the global variable errno for more

information about the error.• EDT_TMOERR - timed out waiting for reply from firmware• EDT_WKACT - already transmitting wink• EDT_WKSIG - cannot disable insertion when transmitting wink


! See Also

• dt_setparm( )• dt_setsigmod( )• dt_settssig( )

159

6. Application GuidelinesThis chapter offers advice and suggestions to guide programmers in designingand coding a digital network interface application.

6.1. Writing a Simple Application

This chapter is not meant to be a comprehensive guide to developing ordebugging digital network interface applications. Instead, the following sectionsprovide digital network interface general and task-specific programmingguidelines:

• General Guidelines• Initialization• Processing• Terminating• Compiling and Linking• Aborting

6.1.1. General Guidelines

The following general guidelines for writing applications are explained in thissection.

• Use symbolic defines• Include header files• Check return codes

Use Symbolic Defines

Do not use a numerical value in your application when an equivalent symbolicdefine is available.

Include Header Files

Various header files must be included in your application to test for errorconditions, to use other library functions from this release or to perform eventmanagement and standard attribute functions. An example is shown below. SeeSection 4.3. Include Files, for details.


160


NOTE: To avoid redundancy in the remaining programming examples in thischapter, #include statements will not be shown.

Check Return Codes

Most digital network interface library functions return a value of -1 if they fail(extended attribute functions return AT_FAILURE or AT_FAILUREP if theyfail). Any call to a digital network interface library function should check for areturn value indicating an error. This can be done using a format similar to thefollowing:

/* call to digital network interface library function */

if (dt_xxx(arguments) == -1) { /* error handling routine */} /* successful function call - continue processing ... */

Using this technique ensures that all errors resulting from a digital networkinterface device library call will be trapped and handled properly by theapplication. In many cases, you can check for a return value of other than zero(0), as shown in the example below. However, this should only be used where anon-zero value is returned when the function fails. See Section 4.2. ErrorHandling, or Chapter 5. Function Reference, for function specific details.

6. Application Guidelines

161

. . . /* error handling routine */ void do_error( devh, funcname ) int devh; char *funcname; { int errorval = ATDV_LASTERR( devh ); printf( "Error while calling function %s on device %s. \n", funcname, ATDV_NAMEP( devh ) ); if ( errorval == EDT_SYSTEM ) { printf( "errno = %d\n", errno ); perror(""); } else { printf( "Error value = %d\n Error message = %s\n", errorval,ATDV_ERRMSGP( devh ) ); } return; }

main( ) { . . .

/* call to DTI/xxx library function */ if (dt_setevtmsk( devh, DTG_SIGEVT, 0, DTA_SETMSK ) ) != 0) { do_error( devh, "dt_setevtmsk()" ); }

/* successful function call - continue processing ... */ . . .}

NOTES: 1. Calls to dt_open( ) return either -1 or a non-zero device handle,therefore, when issuing the dt_open( ) function, check for a returnof -1. The specific error can be found in the global variable errno,contained in errno.h. Calls to ATDT_BDSGBIT( ) return thepointer AT_FAILUREP when the function fails.

2. To avoid redundancy in the remaining programming examples inthis chapter, the do_error( ) function will not be shown.

The dtilib.h header file lists symbolic defines for the error.


162

6.1.2. Initialization

Before a digital network interface application can perform any processing oraccess devices, it should initialize the digital network interface hardware to reflectthe physical configuration of your system and set other parameters needed tosupport the application. Tasks that are performed as a part of initializationgenerally include:

• Set hardware configuration• Set alarm handling parameters and masks• Initialize time slots

These involve the following digital network interface device functions:

• dt_setalrm( )• dt_setevtmsk( )• dt_setidle( )• dt_setparm( )• dt_setsigmod( )• dt_settssig( )

NOTE: Preferably, parameters set by dt_setparm( ) are those that must bechanged while the application is running or that cannot be set throughthe download parameter file (see the Software Installation Guide (forLinux or Windows).

Set Hardware Configuration

Use dt_setparm( ) to set hardware configuration, test mode, clock source, andnetwork telephony parameters. Specific settings include:

• Cable type connecting the digital network interface device to the network• Loopback test mode• Clock source (see dt_setparm( ) in Chapter 5. Function Reference for an

example)• Wink detection and transmission duration


163

NOTE: If your application uses the dt_xmitwink( ) function for receipt ofAutomatic Number Identification (ANI) or Direct Number IdentificationService (DNIS) digits, you must make sure that digital network interfacewink duration conforms to the proper protocol requirements. Consultyour carrier for details.

For specific parameter or mask values to use for configuring your hardware, seethe relevant function description(s) in Chapter 5. Function Reference.

Set Alarm Handling Parameters and Masks

Use dt_setalrm( ) to set the alarm handling mode for each digital networkinterface device. Recommended settings are shown in Table 7. Seedt_setalrm( ) in Chapter 5. Function Reference for an example of setting thealarm handling mode.

Table 7. Recommended dt_setalrm( ) Settings

Telephony Standard Configuration Alarm Handling Mode

T1 terminate DTA_TERMdrop and insert DTA_DROP

E1 terminate DTA_TERMdrop and insert DTA_TERM <check>

Use dt_setevtmsk( ) to set the alarm handling masks for each digital networkinterface device. At a minimum, your application must set masks to detect the T1or E1 alarm conditions listed below.

NOTE: Unless your application is running in poll mode, your application mustissue the SRL sr_enbhdlr( ) function to enable trapping of the eventreturn before setting alarm handling masks with dt_setevtmsk( ). Youmust enable event handlers when running in callback or signal mode.See Section 6.2. Adding Advanced Features, for more details.


164

T1 alarm masks:• DTEC_B8ZSD - (bipolar eight zero subs detection)• DTEC_BPVS - (bipolar violation count saturation)• DTEC_BVCS - (bipolar violation count saturation)• DTEC_DPM - (driver performance monitor restored)• DTEC_ECS - (error count saturation)• DTEC_FERR - (frame bit error)• DTEC_LOS - (loss of signal notification)• DTEC_OOF - (OOF condition mask)• DTEC_RBL - (receive blue alarm)• DTEC_RCL - (receive carrier loss)• DTEC_RCLX - (receive carrier loss)• DTEC_RED - (receive red alarm)• DTEC_RLOS - (receive loss of sync)• DTEC_RYEL - (receive yellow alarm)

E1 alarms:• DEEC_BPVS - (bipolar violation count saturation)• DEEC_CECS - (CRC4 error count saturation)• DEEC_DPM - (driver performance monitor)• DEEC_ECS - (error count saturation notification)• DEEC_FSERR - (frame sync error)• DEEC_LOS - (loss of signal notification)• DEEC_MFSERR - (multiframe sync error)• DEEC_RDMA - (receive distant multiframe alarm)• DEEC_RLOS - (receive loss of sync)• DEEC_RRA - (receive remote alarm)• DEEC_RSA1 - (receive signaling all 1s alarm)• DEEC_RUA1 - (receive unframed all 1s alarm)

Initialize Time Slots

Before making or receiving any calls, an application should initialize all timeslots to a known state. Initialization consists of:

• Clearing/setting all signaling event masks• Setting time slots to the idle state• Setting the proper signaling mode• Idling the time slots


165

Setting event masks to a known state helps ensure that the application receivesonly those events it �expects� and can handle appropriately. Use dt_setevtmsk( )to set the signaling event masks to the desired state.

Setting all time slots to the idle state at the start of your application helps ensurethat off-hook/on-hook transitions will be processed correctly. Use dt_settssig( )to set the state of a time slot to idle.

To generate system signaling from the digital network interface board, it must bein the signaling insertion mode. In this mode, signaling from a resource board,such as a D/300SC-E1, will be overwritten by the digital network interface board.

NOTES: 1. Before idling a T1 time slot, set the signaling mode to signalinginsertion. Use dt_setsigmod( ) to initialize digital network interfacetime slots signaling insertion mode (DTM_SIGINS), as required.

2. To transmit a wink to the network, the digital network interface timeslot on which the wink is to be transmitted must be set to signalinginsertion.

Use dt_setidle( ) to idle a time slot.

The programming example below represents a typical initialization routine for asingle time slot on a single board in a T1 environment.

int init( ){ int dti1; /* open time slot 1 on D/240SC-T1 board 1 ("dti1") */ . . . /* Set time slot "onhook" */ if ( dt_onhook ( dtiB1T1 ) !=0 ) { do_error( dti1, "dt_onhook( ) " ); exit( 1 ); } /* Reset all signaling event masks */ if ( dt_setevtmsk( dti1, DTG_SIGEVT, 0, DTA_SETMSK ) !=0 ) { do_error( dti1, "dt_setevtmsk()" ); exit ( 1 ); }}int dt_onhook ( devh) int devh;{ int retval;


166

/* * Transmit AOFF and BOFF */ if ( ( retval = dt_settssig( devh, DTB_ABIT | DTB_BBIT, DTA_SUBMSK ) ) != 0 ) { do_error( devh, "dt_settssig()"); return ( retval ); } /* * Set signaling mode to signaling insertion */ if ( ( retval = dt_setsigmod( devh, DTM_SIGINS ) ) != 0 ) { do_error( devh, "dt_setsigmod()"); return ( retval ); } /* * Enable idle transmission */ if ( ( retval = dt_setidle( devh, DTIS_ENABLE ) ) != 0 ) { do_error( devh, "dt_setidle()"); } return ( retval );}

The dt_setevtmsk( ) function disables generation of signaling events (seeAppendix A - Standard Runtime Library or Chapter 5. Function Reference fordetails).

The dt_onhook( ) routine is a user-defined function that forces the selected timeslot to the on-hook, idle state using three separate library functions.

The dt_setsigmod( ) function sets the time slot to signaling insertion mode.(This enables the device to transmit idle on the time slot without overridingsignaling.)

The dt_settssig( ) function forces the time slot to the on-hook state.

NOTE: This example assumes that clearing both the A-bits and B-bits is equal tothe on-hook state. Your carrier service may differ.

The dt_setidle( ) function transmits an idle pattern to the network on the selectedtime slot.

NOTE: When two digital network interface boards are arranged in drop-and-insert configuration, dt_setidle( ) can be used to disable pass-throughoperation. Transmitting idle overrides voice data being passed betweennetwork devices on the selected time slot(s).


167

6.1.3. Processing

The main processing tasks for a digital network interface application involve:

• Opening digital network interface board and time slot devices• Establishing connections

Opening and Using Board and Time Slot Devices

Both Linux and Windows open and close devices in the same manner that theyopen and close files. The operating systems view digital network interface boardsand time slot devices as special files. When you open a file, a unique filedescriptor is returned for that file. For example:

int file_descriptor; file_descriptor = open(filename,mode);

Any subsequent action you perform on that file is accomplished by identifyingthe file using file_descriptor. No action at all can be performed on the file untilit is first opened. Devices work in a similar fashion. You must first open adevice before you can perform an operation with it. When you open a device, thevalue returned is a unique handle for that process:

int device_handle; device_handle = dt_open(device_name,mode);

NOTE: A device handle is NOT the same handle returned by an open( ) systemcall.

The digital network interface device driver treats time slot and logical boarddevices similarly. Each is referred to by using a device handle. Any time youwant to use the device, you must identify the device with its handle. A time slotdevice is an individual T1 or E1 time slot; for example, 1 of the 30 time slots on aDTI/300SC. A DTI/300SC is one digital network interface logical board devicecontaining 30 time slot devices.

NOTE: Time slot devices can be opened without opening the board devicecontaining that time slot. (It is unnecessary to open a board deviceunless you are setting or getting a board-level device parameter or alarmhandling.)

Follow the guidelines below when defining devices in the configuration file:


168

Valid device names for DTI devices are found in the /dev directory. For theDTI/xxx boards, the device name format is dtiBx or dtiBxTy, where:

• x represents the digital network interface logical board number• y represents the time slot number, ranging from 1 to 24 (T1) or 1 to 30 (E1)

Valid device names for the D/xxxSC boards are built from the board namespecified in the configuration file. The name of the D/xxxSC device may be inthe form dtiBx, dtiBx, dtiBxTy, or dtiBxTy where:

• x represents the D/xxxSC logical board number• y represents the time slot number, ranging from 1 to 24 (T1) or 1 to 30 (E1)

NOTE: The logical board device number of the D/xxxSC device must not be thesame as the logical board number of the DTI/xxx device.

The following example shows how time slot 1 can be opened on two differentD/240SC-T1 boards. For details on opening and closing devices, refer todt_open( ) in Chapter 5. Function Reference.

int dti1; int dti2;

/* Open device dtiB1T1 */ if ( ( dti1 = dt_open( "dtiB1T1", 0 ) ) == -1 ) { printf( "Cannot open DTI device dtiB1T1\n" ); perror( " " ); exit ( 1 ); }

/* Open device dtiB2T1 */ if ( ( dti2 = dt_open( "dtiB2T1", 0 ) ) == -1 ) { printf( "Cannot open DTI device dtiB2T1\n" ); perror( " " ); exit ( 1 ); }

NOTE: To avoid redundancy in the remaining programming examples in thischapter, the dt_open( ) function will not be shown. The remainingexamples are based on the device name conventions used in theexamples above and assume that the relevant digital network interfacedevices have previously been opened.


169

Establishing Connections

The examples below show how an incoming call can be established.

#include <windows.h> /* For Windows applications only */#include <srllib.h>#include <dtilib.h>#include <errno.h>

int devh; /* Time slot device handle */int retval; /* Function return value */int AON_received = 0; /* AON_received flag */int AON_handler( ){ int event = sr_getevttype( ); int *datap = (int *)sr_getevtdatap( ); short indx; if (event != DTEV_SIG) { printf("Unknown event %d received. Data = %d\n",event,*datap); return 0; } for (indx = 0; indx < 4; indx++) { /* * Check if bit in change mask (upper nibble - lower byte) is * set or if this is a WINK (upper nibble - upper byte) event */ if (!(*datap & (0x1010 << indx))) { continue; } switch (*datap & (0x1111 << indx)) { case DTMM_AON: AON_received = 1; break; . . . default: printf(Signal Event Error: Data = %d\n,*datap); } } return 0;}int wait_ring(){/* * This routine waits for an event from AON_handler to signal * an incoming call */

int devh; /* Time slot device handle */

/* * Open board 1 time slot 1 device (dti1) */ if ( ( devh = dt_open( "dtiB1T1", 0 ) ) == -1 ) { printf( "Cannot open device dtiB1T1. errno = %d", errno ); return ( -1 ); }


170

/* * Enable event handler to catch AON events */ if ( ( retval = sr_enbhdlr( devh, DTEV_SIG, AON_handler ) ) == -1 ) { printf( "Unable to set AON handler for device %s", ATDV_NAMEP ( devh ) ); return( retval ); } /* * Enable AON signaling transition events */ if ( ( retval = dt_setevtmsk( devh, DTG_SIGEVT, DTMM_AON, DTA_SETMSK ) ) == -1 ) { printf ( "Error message = %s.", ATDV_ERRMSGP( devh ) ); return ( retval ); } /* * Now wait for an incoming call */ while( AON_received == 0 ) { sleep( -1 ); /* Sleep until we receive an incoming call */ } /* We have received an incoming call. See next segment. */ . . .}

The AON_handler( ) routine is an asynchronous event handler that flagstransitions of signaling bit �A� to the ON state. When the system detects an A-ON condition, AON_handler( ) sets the AON_received flag to 1. TheAON_handler( ) function uses the SRL sr_enbhdlr( ) function and related eventmanagement functions to determine when a signaling transition occurs. Fordetails, see Appendix A - Standard Runtime Library.

NOTES: 1. Asynchronous signal handling is one of several ways to manageevent notification and is shown for ease of explanation only. Formore information on application development models, refer to theStandard Runtime Library API Programming Guide .

2. This example assumes that setting the A-bit to ON is equal to theoff-hook state. Your carrier service may differ.

The wait_ring( ) routine is a user-defined function that performs the followingtasks:

• Opens a time slot device• Enables trapping of the desired signaling condition for the selected time slot

device• Puts the application to sleep until detection of the appropriate signaling

condition.


171

The dt_open( ) function opens time slot 1 on digital network interface board 1and assigns the returned device handle to variable devh.

The SRL sr_enbhdlr( ) function enables processing by the AON_handlerfunction of any signaling events detected on the device represented by devh (fordetails see Appendix A - Standard Runtime Library).

The dt_setevtmsk( ) function enables detection of signaling bit A-ON transitionson device devh. Using E&M (Ear and Mouth) signaling protocol, a transition ofthe A-bit from OFF to ON signifies a request for service or ring event. Whenenabling event notification, the dt_setevtmsk( ) function should be invoked onlyafter the applicable handler has been enabled; otherwise, events could be missed.In the previous example, the AON_handler( ) function was used.

The while statement puts the routine to sleep until the AON_handler routinedetects a ring event. When a ring event is detected, processing resumes with thefollowing segment.

/* * Continued from previous example */ . .int dt_offhook ( devh)int devh;{ int retval; /* * Transmit AON and BON */ if ( ( retval = dt_settssig( devh, DTB_ABIT | DTB_BBIT, DTA_ADDMSK ) ) != 0 ) { do_error( devh, "dt_settssig()" ); return ( retval ); } /* * Set signaling mode to signaling insertion */ if ( ( retval = dt_setsigmod( devh, DTM_SIGINS ) ) != 0 ) { do_error( devh, "dt_setsigmod()"; return ( retval ); } /* * Disable idle transmission */ if ( ( retval = dt_setidle( devh, DTIS_DISABLE ) ) != 0 ) { do_error( devh, "dt_setidle()" ); } return ( retval );}


172

The dt_offhook( ) routine is a user-defined function that forces the selected timeslot to the off-hook state and disables the transmission of idle using three separatelibrary functions.

NOTE: The dt_offhook( ) function is similar to the dt_onhook( ) functionexplained above, under Initialize Time Slots, in the init( ) example.

The dt_setsigmod( ) function sets the time slot to signaling insertion mode.

NOTE: Setting signaling to insertion mode is necessary if your application willbe generating signaling from the digital network interface board. Togenerate signaling from a Voice or other resource channel, set thesignaling mode to transparent.

The dt_settssig( ) function forces the time slot to the off-hook state.

NOTE: This example assumes that setting the A-bits and B-bits is equal to theoff-hook state. Your carrier service may differ.

The dt_setidle( ) function disables the transmission of the idle pattern to thenetwork on the selected time slot.

6.1.4. Terminating

When your process completes, devices should be shut down in an orderly fashion.Tasks that are performed to terminate an application generally include:

• Disable events• Reset time slots• Close devices

The example that follows is based in part on the processes illustrated in theprevious examples. When your application is done processing a call, thefollowing example should be executed.

NOTE: The following example assumes that relevant devices have beenpreviously opened and variable names have been declared.


173

/* Disable all signaling events for this time slot */if ( dt_setevtmsk( dti1, DTG_SIGEVT, 0, DTA_SETMSK) != 0 ) { do_error( dti1, "dt_setevtmsk()" ); /* Error function */}

/* * Disable event handler for AON events */ if ( ( retval = sr_dishdlr( devh, DTEV_SIG, AON_handler ) ) == -1 ) { printf( "Unable to disable AON handler for device %s", ATDV_NAMEP ( devh ) ); return( retval ); }

/* * close time slot 1 on digital network interface board 1 ("dti1") and digital networkinterface board2 ("dti2") */if ( dt_close( dti1 ) != 0 ) { do_error( dti1, "dt_close()" );}if ( dt_close( dti2 ) != 0 ) { do_error( dti2, "dt_close()" );}

The dt_setevtmsk( ) function disables all currently enabled event notificationmasks. The routine that follows uses SRL functions (not illustrated) to disable allsignal handlers (for SRL details, see Appendix A - Standard Runtime Library).

NOTES: 1. The dt_setevtmsk( ) and any SRL functions must be called in theorder shown in the example.

2. SRL Event Management functions (such as sr_dishdlr( ), whichdisables an event handler) must be called prior to closing the devicethat is sending the handler event notifications (see Appendix A -Standard Runtime Library for SRL details).

The dt_onhook( ) routine is a user-defined function that forces the selected timeslot back to the on-hook, idle state using three separate library functions.

NOTE: The dt_onhook( ) function is identical to the one explained above, underInitialize Time Slots, in the init( ) example segment.

The dt_setsigmod( ) function resets the time slot device to signaling insertionmode.

The dt_settssig( ) function sets the time slot device to the on-hook state, ready foranother call.


174

The dt_setidle( ) function transmits idle on the selected time slot. When twodigital network interface boards are arranged in drop-and-insert configuration,dt_setidle( ) can be used to disable pass-through operation. Transmitting idleoverrides voice data being passed between network devices on the selected timeslot(s).

The dt_close( ) function closes the time slot device.

6.1.5. Compiling and Linking

To compile and link your application, follow the syntax instructions for yourversion of the C Development Package.

NOTE: Make sure when compiling or linking that the SRL library name isspecified last. If your application includes digital network interface andVoice library functions, for instance, use either of the following twolibrary orders on the command line:

-l dti -l dxxx -l srl

or

-l dxxx -l dti -l srl

6.1.6. Aborting

If you abort a digital network interface application by pressing the interrupt key,the system will terminate the current process but may leave devices in anunknown state. The next time you run your application, therefore, you mayencounter errors.

To avoid errors of this type, your application should include an event handler thattraps the interrupt key and performs the actions discussed under Section6.1.4. Terminating.

6.2. Adding Advanced Features

When designing an application, you must test for digital network interface alarm,signaling, and other unsolicited or asynchronous events by constructing one ormore event handlers. An event handler is an application-defined function that iscalled by the Standard Runtime Library (SRL).


175

NOTE: Event handling operations vary with the mode type (i.e., callback,polled, synchronous, etc.) used by your application. For moreinformation on application development models, refer to the StandardRuntime Library API Programming Guide.

WarningTo avoid re-entrance problems, construction of an event handler must

follow the same rules as a signal handler. Consult your systemadministrator or documentation for detailed information.

Calls to the appropriate event handler are managed by SRL. Within a digitalnetwork interface application, event notification may be enabled, disabled, held,and released by a combination of SRL and digital network interface libraryfunctions. For more information, refer to Appendix A - Standard RuntimeLibrary.


176

177

7. Digital Network Interface API forDM3

7.1. Overview of Digital Network Interface API for DM3

The digital network interface API provides limited support for a new generationof Intel Dialogic hardware products that are based on the DM3 mediastreamarchitecture, in addition to original Springware products (also known as earlier-generation products).

This chapter describes the digital network interface API support on DM3 andnotes any differences in the way the API is used on Springware products versusDM3 products.

The term �R4 for DM3� or �R4 on DM3� is used to refer to specific aspects ofthe R4 API interface that relate to support for DM3 boards.

7.2. Digital Network Interface API Function Restrictions

The digital network interface library contains functions for controlling the digitalnetwork interface (E1 or T1) to the PSTN (Public Switched Telephone Network).The digital network interface library includes functions for alarm handling,diagnostics, resource management, SCbus routing and others.

On DM3 boards, most digital network interface functions are not supported sincethe same functionality can be achieved using Global Call. However, the resourcemanagement and TDM bus routing functions are supported as shown in Table8. List of Digital Network Interface API Functions Fully Supported. R4 on DM3now uses the DTI API for Layer 1 alarms. In previous versions of R4 on DM3,the Global Call API handled those alarms (see 7.3. Detecting Layer 1 Alarms).All other DTI functions are not supported.

NOTE: If you execute a network interface library function that is not supportedon DM3 boards, it produces an EDT_NOTIMP (�not implemented�)error.


178

Table 8. List of Digital Network Interface API Functions FullySupported

Function Name Notes

dt_close( ) Supported. Although dt_open( ) and dt_close( ) aresupported on DM3 network interface devices, use ofthe network interface device handle is extremelylimited because the Global Call API providesapplication call control rather than the DTI API. Ingeneral, use the gc_OpenEx( ),gc_GetNetworkH( ), and gc_Close( ) functionsinstead.

dt_getctinfo( ) Supported.dt_getxmitslot( ) Supported.dt_listen( ) Supported.dt_open( ) Supported. See note for dt_close( ).dt_setevtmsk( ) Limitations: Supports enabling layer 1 alarms.

dt_unlisten( ) Supported.dt_xmitalrm( ) Supported.

7.3. Detecting Layer 1 Alarms

On DM3 boards, the digital network interface API allows applications to retrievealarm information that can be used to troubleshoot problems on line devices. TheAPI provides the dt_setevtmsk( ) function to enable an application to configurewhich alarms are to be received.

The dt_setevtmsk( ) function enables and disables notification for events thatoccur on a digital network interface logical board or time slot device. Thisfunction allows the application to set a bitmask of transition events. The bitmaskdetermines which transitions cause an event to be generated.

7. Digital Network Interface API for DM3

179

When using this function, check for DTEV_E1ERRC or DTEV_T1ERRC forE1 or T1 events, respectively.

NOTE: Since dt_getevtmsk( ) is not supported, the application must keep trackof the bitmask of events previously set with the dt_setevtmsk( )function.


180

181

Appendix A - Standard RuntimeLibrary

Digital Network Interface Entries and Returns

The Standard Runtime Library (SRL) is a device independent library containingEvent Management functions, Standard Attribute functions, and the DV_TPTTermination Parameter table. SRL functions and data structures are described indetail in the Standard Runtime Library API Programming Guide . This appendixlists all SRL entries and returns applicable to the digital network interface. Table9 provides a guide to the contents of this appendix.

NOTE: This appendix documents the Standard Runtime Library (SRL), includedin this release. This SRL is fully compatible with the earlier releases ofthe SRL, therefore, existing applications designed to work with earlierversions of the voice software will work with the current voice softwareand SRL. However, we encourage you to upgrade your applications tothe voice software included in this release to take advantage of newfunctionality.


182

Table 9. Guide to Appendix A

Digital Network InterfaceTable SRL Components Data Number

Event Managementfunctions

Digital Network Interface inputs forEvent Management functions

Table 10

Digital Network Interface returnsfrom Event Management functions

Table 11

Standard Attribute functions Digital Network Interface valuesreturned by the Standard Attributefunctions

Table 12

DV_TPT Table Termination conditions and relateddata, required to set the DV_TPT fora Digital Network Interface device

Table 13

NOTE: The header file for this library is srllib.h. It must be �included� inapplication code prior to including dtilib.h. For example:

#include <srllib.h>#include <dtilib.h>

Event Management Functions

The enable processing of unsolicited and asynchronous termination eventsreturned by library functions. For the digital network interface, these functionsinclude:

dt_rundiag( )dt_setevtmsk( )dt_tstcom( )dt_tstdat( )dt_xmitwink( )

Each of the Event Management functions applicable to the digital networkinterface are listed in the following tables. Table 10 shows digital networkinterface-specific inputs and Table 11 shows valid digital network interfacereturns.

Appendix A - Standard Runtime Library

183

Table 10. Digital Network Interface Inputs for Event ManagementFunctions

Event ManagementFunction

Digital NetworkInterface-specific Input

Valid Input Value

sr_enbhdlr( )Enable event handler

evt_type DTEV_T1ERRC - T1 alarmcondition detected

DTEV_E1ERRC - E1 alarmcondition detected

DTEV_SIG - Signalingtransition event detected

DTEV_COMRSP -Successful communications test

DTEV_DATRSP - Responseto data test

DTEV_RETDIAG -Diagnostic complete

DTEV_WINKCPLT - Winktransmission complete

DTEV_RCVPDG - Receivepulse digits

DTEV_PDDONE - Pulse dialcomplete events

DTEV_ERREVT - Errorcondition event

DTEV_MTFCNCPT -Multitasking function complete

sr_dishdlr( )Disable event handler

evt_type Same as above

sr_getevtdev( )Get device handle

device digital network interface devicehandle

sr_getevttype( )Get event type

event type DTEV_T1ERRC

DTEV_E1ERRC


184


Digital NetworkInterface-specific Input

Valid Input Value

DTEV_SIGDTEV_COMRSPDTEV_DATRSPDTEV_RETDIAGDTEV_WINKCPLTDTEV_RCVPDGDTEV_PDDONEDTEV_ERREVTDTEV_MTFCNCPT

sr_getevtlen( )Get event data length

event length Number of bytes in the datareturned

sr_getevtdatap( )Get pointer to eventdata

event data Pointer to event specific data


185

Table 11. Digital Network Interface Returns from Event ManagementFunctions


Digital NetworkInterface-specific Return

Returned Value

sr_getevtdev( )Get device handle

device digital network interfacedevice handle

sr_getevttype( )Get event type

event type DTEV_T1ERRCDTEV_E1ERRCDTEV_SIGDTEV_COMRSPDTEV_DATRSPDTEV_RETDIAGDTEV_WINKCPLTDTEV_RCVPDGDTEV_PDDONEDTEV_ERREVTDTEV_MTFCNCPT

sr_getevtlen( )Get event data length

event length digital network interface eventlength information

sr_getevtdatap( )Get pointer to eventdata

event data digital network interface eventdata pointer information

Standard Attribute Functions

The Standard Attribute functions return general device information, such as thedevice name or the last error that occurred on the device. The Standard Attributefunctions and the digital network interface-specific information they return arelisted in Table 12.


186

Table 12. Standard Attribute Functions

Standard Attribute Function Information Returned for DigitalNetwork Interface

ATDV_ERRMSGP( ) Pointer to string describing the errorthat occurred during the last functioncall on the digital network interface(See the error listing section andfunction reference section of theappropriate software reference)

ATDV_IOPORT( ) Valid port address for the digitalnetwork interface

ATDV_IRQNUM( ) Valid IRQ number rangeATDV_LASTERR( ) The error that occurred during the last

function call on the digital networkinterface (See the error listing sectionand function reference section of theappropriate software reference)

ATDV_NAMEP( ) Pointer to device name (dtiBbXx)ATDV_SUBDEVS( ) Number of subdevices (time slots,

channels, etc.). List digital networkinterface-specific returns. Refer to theStandard Runtime Library APIProgramming Guide for information onsubdevices.


187

PT Structure

The DV_TPT termination parameter table sets termination conditions for a rangeof products. The valid values for the DV_TPT structure in relation to the digitalnetwork interface board are contained in this section.

The DV_TPT structure has the following format:

typedef struct dv_tpt ( unsigned short tp_type; /* Flags describing this entry */ unsigned short tp_termno; /* Termination Parameter number */ unsigned short tp_length; /* Length of terminator */ unsigned short tp_flags; /* Parameter attribute flag */ unsigned short tp_data; /* Optional additional data */ unsigned short rfu; /* Reserved */ DV_TPT *tp_nextp; /* Pointer to next termination * parameter if IO_LINK set */}DV_TPT;

Table 13 shows the digital network interface equates for this structure.

Table 13. DV_TPT Structure

Field Value Description

tp_type IO_LINK Structure is part of a linked list - the structureis linked through the Standard Runtime Library

IO_CONT(default)

The next structure will be contiguous inmemory

IO_EOT This structure is the final entry in the DV_TPTtable

rfu 0 Reserved for future usetp_nextp 0 Pointer to the next termination parameter

Refer to the Standard Runtime Library Programmer�s Guide for furtherinformation on the termination parameter table structure.


188

189

Appendix B - Message Blocks

Command Message Blocks

DTCAS_CREATE_TRANSITION

This command adds a transition template to the signal set. The following figuresillustrate the timing definitions for a transition template.

A

B

A = PreTransIntervalB = PostTransInterval

Figure 13. Transition Timing, Receive

A

B

A = PreTransIntervalNomB = PostTransIntervalNom

Figure 14. Transition Timing, Transmit


190

The signal is not immediately active for detection. The devh handle must be avalid DTI board device handle. The cmdmsgp argument must point to theDTCAS_CREATE_TRANSITION_MSG message block. The reply messagecode, DTCAS_CREATE_TRANSITION_COMPLETE, is received in responseto this command message block. The typedef for theDTCAS_CREATE_TRANSITION_MSG structure is as follows:

typedef struct t_create_transition_msg { unsigned char msg_code; unsigned char flags; unsigned short template_id; unsigned char PreTransCode; unsigned char PostTransCode; unsigned short PreTransInterval; unsigned short PreTransIntervalNom; /* [ci]+ send template addition */ unsigned short PostTransInterval; unsigned short PostTransIntervalNom;} DTCAS_CREATE_TRANSITION_MSG;


msg_code identifies the message type; must be set toDTCAS_CREATE_TRANSITION

flags reserved; must be set to 0 for future compatibilitytemplate_id specifies the template identifierPreTransCode specifies the pattern to be matched/set prior to

transition. See common data type prefixCode forthe format of this field.

PostTransCode specifies the pattern to be matched/set aftertransition. See common data type prefixCode forthe format of this field

PreTransInterval specifies the minimum time for the duration of thepre-transition interval; i.e., the amount of timeduring which the PreTransCode must be present onthe channel to before it begins to look for thetransition to the PostTransCode. See common datatype prefixInterval for the format of this field.


191


PreTransIntervalNom specifies the duration of the pre-transitioninterval for transmission; i.e., the length of time totransmit the PreTransCode. The PreTransCodemust be transmitted for the PreTransIntervalTimevia the dt_settssigsim( ) function. See commondata type prefixInterval for the format of this field.

PostTransInterval specifies the minimum time for the duration of thepost-transition interval; i.e., the amount of timeduring which the PostTransCode must be presenton the channel after the PreTransCode has beendetected for the PreTransInterval time. Seecommon data type prefixInterval for the format ofthis field.

PostTransIntervalNom specifies the duration of the post-transition intervalfor transmission; i.e., the length of time to transmitthe PostTransCode. See common data typeprefixInterval for the format of this field.


192

DTCAS_CREATE_PULSE

This command adds a pulse template to the signal set. The following figuresillustrate the timing definitions for a pulse template.

A

B

C

A = PrePulseIntervalPulseIntervalMin < B < PulseIntervalMaxC = PostPulseInterval

Figure 15. Pulse Timing, Receive

A

B

C

A = PrePulseIntervalNomB = PulseIntervalNomC = PostPulseIntervalNom

Figure 16. Pulse Timing, Transmit

The signal is not immediately active for detection. The devh handle must be avalid DTI board device handle. The cmdmsgp argument must point to theDTCAS_CREATE_PULSE_MSG message block. The reply message code,


193

DTCAS_CREATE_PULSE_COMPLETE, is received in response to thiscommand. The typedef for the DTCAS_CREATE_PULSE_MSG structure is:

typedef struct t_create_pulse_msg { unsigned char msg_code; unsigned char flags; unsigned short template_id; unsigned char OffPulseCode; unsigned char OnPulseCode; unsigned short PrePulseInterval; unsigned short PrePulseIntervalNom; unsigned short PulseIntervalMin; unsigned short PulseIntervalNom; unsigned short PulseIntervalMax; unsigned short PostPulseInterval; unsigned short PostPulseIntervalNom;} DTCAS_CREATE_PULSE_MSG;


msg_code identifies the message type; must be set toDTCAS_CREATE_PULSE

flags reserved; must be set to 0 for future compatibilitytemplate_id specifies the template identifierOffPulseCode specifies the pattern to be matched/set prior to pulse

and after pulse. See common data type prefixCodefor the format of this field.

OnPulseCode specifies the pattern to be matched/set during pulse.See common data type prefixCode for the format ofthis field

PrePulseInterval specifies the minimum time for the duration of thepre-pulse interval; i.e., the amount of time duringwhich the OffPulseCode must be present on thechannel to before it begins to look for the transitionto the OnPulseCode. See common data typeprefixInterval for the format of this field.

PrePulseIntervalNom specifies the duration of the pre-pulse interval fortransmission; i.e., the amount of time to transmit theOffPulseCode prior to transmitting theOnPulseCode. The OffPulseCode must betransmitted for at least PrePulseIntervalTimeNomvia the dt_settssigsim( ) function.. See commondata type prefixInterval for the format of this field.


194


PulseIntervalMin specifies the minimum time for the duration of thepulse interval; i.e., the minimum amount of timeduring which the OnPulseCode must be present onthe channel before it transitions to theOffPulseCode. See common data typeprefixInterval for the format of this field

PulseIntervalMax specifies the maximum time for the duration of thepulse interval; i.e., the maximum amount of timeduring which the OnPulseCode can be present onthe channel before it transitions to theOffPulseCode. See common data typeprefixInterval for the format of this field.

PulseIntervalNom specifies the desired time for the duration of thepulse interval; i.e., the amount of time to transmitthe OnPulseCode prior to transmitting theOffPulseCode. See common data typeprefixInterval for the format of this field.

PostPulseInterval specifies the minimum time for the duration of theend-of-pulse interval; i.e., the minimum amount oftime during which the OffPulseCode must bepresent on the channel after OnPulseCode isdetected for a minimum of PulseIntervalMin and amaximum of PulseIntervalMax. See common datatype prefixInterval for the format of this field.

PostPulseIntervalNom specifies the duration of the end-of-pulse intervalfor transmission; i.e., the amount of time to transmitthe OffPulseCode after transmitting theOnPulseCode for PulseIntervalTime. See commondata type prefixInterval for the format of this field.


195

DTCAS_CREATE_TRAIN

This command adds a pulse train template to the signal set. The following figuresillustrate the timing definitions for a pulse train template.

A

B

C

n morepulses

. . .D

A = PreTrainIntervalPulseIntervalMin < B < PulseIntervalMaxInterPulseIntervalMin < C < InterPulseIntervalMaxD = PostTrainInterval

Figure 17. Pulse Train Timing, Receive

A

B

C D

A = PreTrainIntervalNomB = PulseIntervalNomC = InterPulseIntervalNomD = PostTrainIntervalNom

Figure 18. Pulse Train Timing, Transmit


196

The signal is not immediately active for detection. The devh handle must be avalid DTI board device handle. The cmdmsgp argument must point to theDTCAS_CREATE_TRAIN_MSG message block. The reply message code,DTCAS_CREATE_TRAIN_COMPLETE is received in response to thiscommand. The typedef for the DTCAS_CREATE_TRAIN_MSG structure is asfollows:

typedef struct t_create_train_msg { unsigned char msg_code; unsigned char flags; unsigned short template_id; unsigned char OffPulseCode; unsigned char OnPulseCode; unsigned short PreTrainInterval; unsigned short PreTrainIntervalNom; unsigned short PulseIntervalMin; unsigned short PulseIntervalNom; unsigned short PulseIntervalMax; unsigned short InterPulseIntervalMin; unsigned short InterPulseIntervalNom; unsigned short InterPulseIntervalMax; unsigned short PostTrainInterval; unsigned short PostTrainIntervalNom;} DTCAS_CREATE_TRAIN_MSG;


msg_code identifies the message type; must be set toDTCAS_CREATE_TRAIN

flags reserved; must be set to 0 for futurecompatibility

template_id specifies the template identifierOffPulseCode specifies the pattern to be matched/set prior to

pulse and after pulse. See common data typeprefixCode for the format of this field.

OnPulseCode specifies the pattern to be matched/set duringpulse. See common data type prefixCode for theformat of this field.


197


PulseIntervalMin specifies the minimum time for the duration ofthe pulse interval; i.e., the minimum amount oftime during which the OnPulseCode must bepresent on the channel before it transitions to theOffPulseCode. This field should not be set tozero. See common data type prefixInterval forthe format of this field.

PulseIntervalMax specifies the maximum time for the duration ofthe pulse interval; i.e., the maximum amount oftime during which the OnPulseCode can bepresent on the channel before it transitions to theOffPulseCode. This parameter should be set to avalue that is greater then the PulseIntervalNomparameter. See common data type prefixIntervalfor the format of this field.

PulseIntervalNom specifies the desired time for the duration of thepulse interval; i.e., the amount of time totransmit the OnPulseCode prior to transmittingthe OffPulseCode. This parameter should be setto a value greater then the PulseIntervalMinparameter. See common data type prefixIntervalfor the format of this field.

PreTrainInterval specifies the minimum time for the duration ofthe pre-train interval; i.e., the amount of timeduring which the OffPulseCode must be presenton the channel to before it begins to look for thefirst transition to the OnPulseCode. This timemay differ from the pre-pulse time of thecomponent pulses. See common data typeprefixInterval for the format of this field.


198


PreTrainIntervalNom specifies the duration of the pre-train interval fortransmission; i.e., the amount of time to transmitthe OffPulseCode prior to transmitting the firstOnPulseCode. The OffPulseCode must betransmitted via the dt_settssigsim( ) function forat least the PreTrainIntervalTime. See commondata type prefixInterval for the format of thisfield.

InterPulseIntervalMin specifies the minimum time for the duration ofthe inter-pulse interval; i.e., the minimumamount of time during which the OffPulseCodemust be present on the channel after havingreceived OnPulseCode for at leastPulseIntervalMin and no longer thenPulseIntervalMax. See common data typeprefixInterval for the format of this field.

InterPulseIntervalMax specifies the maximum time for the duration ofthe inter-pulse interval; i.e., the maximumamount of time during which the OffPulseCodecan be present on the channel after havingreceived OnPulseCode for at leastPulseIntervalMin and no longer thenPulseIntervalMax. See common data typeprefixInterval for the format of this field.

InterPulseIntervalNom specifies the desired time for the duration of theinter-pulse interval; i.e., the amount of time totransmit the OffPulseCode after transmission ofthe OnPulseCode for PulseIntervalNom.. Seecommon data type prefixInterval for the formatof this field.


199


PostTrainInterval specifies the minimum time for the duration ofthe end-of-train interval; i.e., the minimumamount of time during which the OffPulseCodemust be present on the channel after the lastOnPulseCode is detected for a minimum ofPulseIntervalMin and a maximum ofPulseIntervalMax. See common data typeprefixInterval for the format of this field.

PostTrainIntervalNom specifies the minimum time for the duration ofthe end-of-train interval; i.e., the amount of timeto transmit the OffPulseCode after transmittingthe last OnPulseCode for PulseIntervalTime.See common data type prefixInterval for theformat of this field.


200

DTCAS_DELETE_TEMPLATE

This command removes a signal template definition from the signal set. Thedevh handle must be a valid DTI board device handle. The cmdmsgp argumentmust point to the DTCAS_DELETE_TEMPLATE_MSG message block. Thereply message code, DTCAS_DELETE_TEMPLATE_COMPLETE, is receivedin response to this command. The typedef for theDTCAS_DELETE_TEMPLATE_MSG structure is as follows:

typedef struct t_delete_template_msg { unsigned char msg_code; unsigned char rfu; unsigned short template_id;} DTCAS_DELETE_TEMPLATE_MSG;


msg_code identifies the message type and must be set toDTCAS_DELETE_TEMPLATE

rfu reserved; must be set to 0 for future compatibilitytemplate_id specifies the template identifier


201

DTCAS_ENABLE_TEMPLATE

This command enables CAS signal definition in a signal set for a particularchannel. Enabling a signal which is already enabled is considered an error,because recognition of the signal could already be in progress based on earlierevents. The devh handle must be a valid DTI channel device handle. Thecmdmsgp argument must point to the DTCAS_ENA_DIS_TEMPLATE_MSGcommand message block. The reply message code,DTCAS_ENABLE_TEMPLATE_COMPLETE, is received in response to thiscommand. The typedef for the DTCAS_ENA_DIS_TEMPLATE_MSG structureis as follows:

typedef struct t_ena_dis_template_msg { unsigned char msg_code; unsigned char rfu; unsigned short template_id;} DTCAS_ENA_DIS_TEMPLATE_MSG;


msg_code identifies the message type; must be set toDTCAS_ENABLE_TEMPLATE



202

DTCAS_DISABLE_TEMPLATE

This command disables a CAS signal definition in a signal set for a particularchannel. Disabling a signal which is already disabled is considered a successfuloperation. The devh handle must be a valid DTI channel device handle. Thecmdmsgp argument must point to the DTCAS_ENA_DIS_TEMPLATE_MSGcommand. The reply message code,DTCAS_DISABLE_TEMPLATE_COMPLETE, is received in response to thiscommand. The typedef for the DTCAS_ENA_DIS_TEMPLATE_MSG structureis as follows:

typedef struct t_disable_template_msg { unsigned char msg_code; unsigned char rfu; unsigned short template_id;} DTCAS_ENA_DIS_TEMPLATE_MSG;


msg_code identifies the message type and must be set toDTCAS_DISABLE_TEMPLATE



203

DTCAS_TRANSMIT_TEMPLATE

This command transmits a CAS signal in a signal set for a particular channel.The devh handle must be a valid DTI channel device handle. The cmdmsgpargument must point to the DTCAS_TRANSMIT_MSG command. The replymessage code, DTCAS_TRANSMIT_TEMPLATE_COMPLETE, is received inresponse to this command. The typedef for the DTCAS_TRANSMIT_ MSGstructure is as follows:

typedef struct t_transmit_msg{ unsigned char msg_code; unsigned char rfu; unsigned short template_id; unsigned char pulse_count; unsigned char sequence_count;} DTCAS_TRANSMIT_MSG;


msg_code identifies the message type and must be set toDTCAS_TRANSMIT_TEMPLATE

rfu reserved; must be set to 0 for future compatibilitytemplate_id specifies the template identifierpulse_count specifies the number of pulses to send in a pulse-train.

This field must be set to 1 when sending a signal transitionor a pulse.

sequence_count reserved for future use; must be set to 0


204

Reply Message Blocks

DTCAS_CREATE_TRANSITION_COMPLETE

This reply message is sent in response to a DTCAS_CREATE_TRANSITIONcommand. The result code within the reply message block indicates the successor failure of the command. The buffer referenced by the replymsgp argumentwill contain a valid DTCAS_REPLY_MSG message block if dt_castmgmt( )completes successfully. The typedef for the DTCAS_REPLY_MSG structure isas follows:

typedef struct t_create_reply_msg { unsigned char msg_code; unsigned char rfu; unsigned short template_id; unsigned short result;} DTCAS_REPLY_MSG;


msg_code identifies the message type and must be set toDTCAS_CREATE_TRANSITION_COMPLETE

rfu reserved; must be set to 0 for future compatibilitytemplate_id specifies the template identifierresult indicates the success or failure of the command. This field set

to 0 on success, or one of the following error values if thecommand fails:• DTCAS_ERR_SIGNAL_ID - Duplicate template in table

• DTCAS_ERR_SIGNAL_TABLE_FULL - The signaldefinition table is full


205

DTCAS_CREATE_PULSE_COMPLETE

This reply message is sent in response to a DTCAS_CREATE_PULSEcommand. The result code within the reply message block indicates the successor failure of the command. The buffer referenced by the replymsgp argumentwill contain a valid DTCAS_REPLY_MSG message block if dt_castmgmt( )completes successfully. The typedef for the DTCAS_REPLY_MSG structure isas follows:

typedef struct t_create_reply_msg { unsigned char msg_code; unsigned char rfu; unsigned short template_id; unsigned short result; } DTCAS_REPLY_MSG;


msg_code identifies the message type; must be set toDTCAS_CREATE_PULSE_COMPLETE

rfu reserved; must be set to 0 for future compatibility template_id specifies the template identifier result indicates the success or failure of the command. This field

set to 0 on success, or one of the following error values ifthe command fails:

• DTCAS_ERR_SIGNAL_ID - Duplicate template intable

• DTCAS_ERR_SIGNAL_TABLE_FULL - The signaldefinition table is full

• DTCAS_ERR_PULSE_MIN - The Pulse Min Time is 0. • DTCAS_ERR_PIMN_GTE_PINM - The Pulse Nom is

less than Pulse Min • DTCAS_ERR_PINM_GTE_PIMX - The Pulse Nom

equals or exceeds Pulse Max


206

DTCAS_CREATE_TRAIN_COMPLETE

This reply message is sent in response to a DTCAS_CREATE_TRAINcommand. The result code within the reply message block indicates the successor failure of the command. The buffer referenced by the replymsgp argumentwill contain a valid DTCAS_REPLY_MSG message block if dt_castmgmt( )completes successfully. The typedef for the DTCAS_REPLY_MSG structure isas follows:



msg_code identifies the message type; must be set toDTCAS_CREATE_TRAIN_COMPLETE

rfu reserved; must be set to 0 for future compatibility template_id specifies the template identifier result indicates the success or failure of the command. This field set

to 0 on success, or one of the following error values if thecommand fails:

• DTCAS_ERR_SIGNAL_ID - Duplicate template in table • DTCAS_ERR_SIGNAL_TABLE_FULL - The signal

definition table is full • DTCAS_ERR_PULSE_MIN - The Pulse Min Time is 0 • DTCAS_ERR_PIMN_GTE_PINM - The Pulse Nom is less

than Pulse Min • DTCAS_ERR_PINM_GTE_PIMX - The Pulse Nom equals

or exceeds Pulse Max • DTCAS_ERR_POSTINT_LTE_IPIMX - The Train Post-

Interval is less than or equal to the inter pulse interval


207

DTCAS_DELETE_TEMPLATE_COMPLETE

This reply message is sent in response to a DTCAS_DELETE_TEMPLATEcommand. The result code within the reply message block indicates the successor failure of the command. The buffer referenced by the replymsgp argumentwill contain a valid DTCAS_REPLY_MSG message block if dt_castmgmt( )completes successfully. The typedef for the DTCAS_REPLY_MSG structure isas follows:



msg_code identifies the message type; must be set toDTCAS_DELETE_TEMPLATE_COMPLETE



• DTCAS_ERR_TEMPLATE_NOT_DEFINED - Thetemplate was not found in the template table

• DTCAS_ERR_TEMPLATE_TABLE_EMPTY - TheTemplate table is empty; no templates are defined


208

DTCAS_ENABLE_TEMPLATE_COMPLETE

This reply message is sent in response to a DTCAS_ENABLE_TEMPLATEcommand. The result code within the reply message block indicates the successor failure of the command. The buffer referenced by the replymsgp argumentwill contain a valid DTCAS_REPLY_MSG message block if dt_castmgmt( )completes successfully. The typedef for the DTCAS_REPLY_MSG structure isas follows:



msg_code identifies the message type; must be set toDTCAS_ENABLE_TEMPLATE_COMPLETE.



• DTCAS_ERR_TEMPLATE_NOT_DEFINED - Thetemplate was not found


209

DTCAS_DISABLE_TEMPLATE_COMPLETE

This reply message is sent in response to a DTCAS_DISABLE_TEMPLATEcommand. The result code within the reply message block indicates the successor failure of the command. The buffer referenced by the replymsgp argumentwill contain a valid DTCAS_REPLY_MSG message block if dt_castmgmt( )completes successfully. The typedef for the DTCAS_REPLY_MSG structure isas follows:



msg_code identifies the message type; must be set toDTCAS_DISABLE_TEMPLATE_COMPLETE




• DTCAS_ERR_SIGNAL_NOT_ENABLED - Attemptedto disable a signal pattern that wasn�t enabled


210

DTCAS_TRANSMIT_TEMPLATE_COMPLETE

This reply message is sent in response to a DTCAS_TRANSMIT_TEMPLATEcommand. The result code within the reply message block indicates the successor failure of the command. The buffer referenced by the replymsgp argumentwill contain a valid DTCAS_REPLY_MSG message block if dt_castmgmt( )completes successfully. The typedef for the DTCAS_REPLY_MSG structure isas follows:

typedef struct t_create_reply_msg { unsigned char msg_code; unsigned char rfu; unsigned short template_id; unsigned short result;} DTCAS_REPLY_MSG;


msg_code identifies the message type; must be set toDTCAS_TRANSMIT_TEMPLATE_COMPLETE

rfu reserved; must be set to 0 for future compatibilitytemplate_id specifies the template identifierresult indicates the success or failure of the command. This field



• DTCAS_ERR_TEMPLATESENDNOTDONE -Sending of a template is not finished yet


211

Unsolicited Events

DTEV_CASTEVT

This event type is sent for all unsolicited CAS DTI messages sent to theapplication. The sr_getevtdatap( ) function must be used to return a pointer tothe associated DTCAS_DETECTED_MSG message block. The typedef for theDTCAS_DETECTED_MSG structure is as follows:

typedef struct t_detected_msg { unsigned char msg_code; unsigned char flags; unsigned short template_id; unsigned short result; unsigned short count; unsigned int timestamp; } DTCAS_DETECTED_MSG;


msg_code identifies the message type; must be set toNTT_CAS_TEMPLATE_MATCH

flags reserved; must be set to 0 for future compatibility template_id identifies the template detected count identifies the number of pulses detected timestamp identifies the time of occurrence of this event, and is a

value of the VTRX system clock. Each tick represents 1millisecond, and the granularity of the timestamp is 10;since this is VTRX system clock, this could be used by theapplication as a relative time


212

DTEV_CASSENDENDEVT

This event type is sent to the application after an application initiated signalpattern transmission is complete. The sr_getevtdatap( ) function must be used toreturn a pointer to the associated DTCAS_END_TRANSMIT_MSG messageblock. The typedef for the DTCAS_END_TRANSMIT_MSG structure is asfollows:

typedef struct t_detected_msg { unsigned char msg_code; unsigned char rfu; unsigned short template_id; unsigned short pulse_count; unsigned short sequence_count; unsigned int timestamp; } DTCAS_DETECTED_MSG;


msg_code identifies the message type; must be set toNTT_CAS_TEMPLATE_SEND_END

rfu reserved; must be set to 0 for future compatibility template_id identifies the template detected pulse_count identifies the number of pulses detected sequence_count reserved for future use; should be ignored by the

application timestamp identifies the time of occurrence of this event, and is a

value of the VTRX system clock. Each tick represents 1millisecond, and the granularity of the timestamp is 10;since this is VTRX system clock, this could be used bythe application as a relative time

213

Appendix C - dticas.h Header File

/***************************************************************************** * Copyright (c) 1990-2002 Intel Corporation * All Rights Reserved. All names, products, and services mentioned herein * are the trademarks or registered trademarks of their respective organizations * and are the sole property of their respective owners *****************************************************************************/

/***************************************************************************** * Filename: dticas.h * DESCRIPTION: DTI CAS template definitions.. *****************************************************************************/

#ifndef __DTICAS#define __DTICAS

typedef struct t_create_transition_msg{ BYTE msg_code; BYTE rfu; WORD template_id; BYTE PreTransCode; BYTE PostTransCode; WORD PreTransInterval; WORD PreTransIntervalNom; /* [ci]+ send template adition */ WORD PostTransInterval; WORD PostTransIntervalNom; /* [ci]+ send template adition */} DTCAS_CREATE_TRANSITION_MSG;

typedef DTCAS_CREATE_TRANSITION_MSG *P_DTCAS_CREATE_TRANSITION_MSG;

typedef struct t_create_pulse_msg{ BYTE msg_code; BYTE rfu; WORD template_id; BYTE OffPulseCode; BYTE OnPulseCode; WORD PrePulseInterval; WORD PrePulseIntervalNom; /* [ci]+ send template adition */ WORD PulseIntervalMin; WORD PulseIntervalNom; WORD PulseIntervalMax; WORD PostPulseInterval; WORD PostPulseIntervalNom; /* [ci]+ send template adition */} DTCAS_CREATE_PULSE_MSG;

typedef DTCAS_CREATE_PULSE_MSG *P_DTCAS_CREATE_PULSE_MSG;

typedef struct t_create_train_msg{ BYTE msg_code; BYTE rfu;


214

WORD template_id; BYTE OffPulseCode; BYTE OnPulseCode; WORD PreTrainInterval; WORD PreTrainIntervalNom; /* [ci]+ send template adition */ WORD PulseIntervalMin; WORD PulseIntervalNom; WORD PulseIntervalMax; WORD InterPulseIntervalMin; WORD InterPulseIntervalNom; WORD InterPulseIntervalMax; WORD PostTrainInterval; WORD PostTrainIntervalNom; /* [ci]+ send template adition */} DTCAS_CREATE_TRAIN_MSG;

typedef DTCAS_CREATE_TRAIN_MSG *P_DTCAS_CREATE_TRAIN_MSG;

typedef struct t_create_reply_msg{ BYTE msg_code; BYTE rfu; WORD template_id; WORD result;} DTCAS_REPLY_MSG;

typedef DTCAS_REPLY_MSG *P_DTCAS_REPLY_MSG;

typedef struct t_delete_template_msg{ BYTE msg_code; BYTE rfu; WORD template_id;} DTCAS_DELETE_TEMPLATE_MSG;

typedef DTCAS_DELETE_TEMPLATE_MSG *P_DTCAS_DELETE_TEMPLATE_MSG;

typedef struct t_ena_dis_template_msg{ BYTE msg_code; BYTE rfu; WORD template_id;} DTCAS_ENA_DIS_TEMPLATE_MSG;

typedef DTCAS_ENA_DIS_TEMPLATE_MSG *P_DTCAS_ENA_DIS_TEMPLATE_MSG;

/* (11/22/1999): Additional Structure defined to add new commands to CAS management function */

typedef struct t_get_template_msg{ BYTE msg_code; BYTE rfu; WORD template_id;} DTCAS_GET_TEMPLATE_MSG;

typedef DTCAS_GET_TEMPLATE_MSG *P_DTCAS_GET_TEMPLATE_MSG;


215

typedef struct t_get_next_template_msg{ BYTE msg_code; BYTE rfu; WORD template_id;} DTCAS_GET_NEXT_TEMPLATE_MSG;

typedef DTCAS_GET_NEXT_TEMPLATE_MSG *P_DTCAS_GET_NEXT_TEMPLATE_MSG;

typedef struct t_clear_all_template_msg{ BYTE msg_code; BYTE rfu; WORD template_id;} DTCAS_CLEAR_ALL_TEMPLATE_MSG;

typedef DTCAS_CLEAR_ALL_TEMPLATE_MSG *P_DTCAS_CLEAR_ALL_TEMPLATE_MSG;

typedef struct t_get_template_reply_msg{ BYTE msg_code; BYTE rfu; WORD template_id; WORD result; union template_reply_msg { DTCAS_CREATE_TRANSITION_MSG transition; DTCAS_CREATE_PULSE_MSG pulse; DTCAS_CREATE_TRAIN_MSG train; } tmplt_info;} DTCAS_GET_TEMPLATE_REPLY_MSG;

typedef DTCAS_GET_TEMPLATE_REPLY_MSG *P_DTCAS_GET_TEMPLATE_REPLY_MSG;

/* End addition dated 1/27/2000 */

typedef struct t_detected_msg{ BYTE msg_code; BYTE rfu; WORD template_id; WORD result; WORD count; DWORD timestamp;} DTCAS_DETECTED_MSG;

typedef DTCAS_DETECTED_MSG *P_DTCAS_DETECTED_MSG;

/* [ci] send template addition */typedef struct t_transmit_msg{ BYTE msg_code; BYTE rfu; WORD template_id; BYTE pulse_count; BYTE sequence_count;} DTCAS_TRANSMIT_MSG;


216

typedef DTCAS_TRANSMIT_MSG *P_DTCAS_TRANSMIT_MSG;

typedef struct t_end_transmit_msg{ BYTE msg_code; BYTE rfu; WORD template_id; BYTE pulse_count; BYTE sequence_count; DWORD timestamp;} DTCAS_END_TRANSMIT_MSG;

typedef DTCAS_END_TRANSMIT_MSG *P_DTCAS_END_TRANSMIT_MSG;/* [ci] send template addition */

/* Message code definitions. */

/* Commands: */#define DTCAS_CREATE_TRANSITION 0#define DTCAS_CREATE_PULSE 1#define DTCAS_CREATE_TRAIN 2#define DTCAS_DELETE_TEMPLATE 3#define DTCAS_ENABLE_TEMPLATE 4#define DTCAS_DISABLE_TEMPLATE 5#define DTCAS_TRANSMIT_TEMPLATE 6#define DTCAS_GET_TEMPLATE 7 /* Get a template definition (1/27/2000) */#define DTCAS_GET_NEXT_TEMPLATE 8 /* Get a definition of next template (1/27/2000) */#define DTCAS_CLEAR_ALL_TEMPLATE 9 /* Clear the template queue (1/27/2000) */

/* Replies: */#define DTCAS_CREATE_TRANSITION_COMPLETE 0#define DTCAS_CREATE_PULSE_COMPLETE 1#define DTCAS_CREATE_TRAIN_COMPLETE 2#define DTCAS_DELETE_TEMPLATE_COMPLETE 3#define DTCAS_ENABLE_TEMPLATE_COMPLETE 4#define DTCAS_DISABLE_TEMPLATE_COMPLETE 5#define DTCAS_TRANSMIT_TEMPLATE_COMPLETE 6#define DTCAS_GET_TEMPLATE_COMPLETE 7 /* Template definition received (1/27/2000) */#define DTCAS_GET_NEXT_TEMPLATE_COMPLETE 8 /* Definition of next template received (1/27/2000) */#define DTCAS_CLEAR_ALL_TEMPLATE_COMPLETE 9 /* Clearing template queue completed (1/27/2000) */

/* * Note: The result codes 1-15 are not implemented yet and are reserved for * future use. */

/* Result Codes: */#define DTCAS_ERR_SIGNAL_ID 0x10 /* Identical template creation requested */#define DTCAS_ERR_SIGNAL_TABLE_FULL 0x11 /* The signal definition table is full */#define DTCAS_ERR_POSTINT_LTE_ITIMX 0x25 /* Post Interval Nom <= Inter-Train Interval Max */#define DTCAS_ERR_ITIMX_LTE_IPIMX 0x26 /* Inter-Train Max is <= Inter-Pulse Max */#define DTCAS_ERR_INT_TRAIN_MIN 0x27 /* Inter-Train Min Time cannot be 0 */#define DTCAS_ERR_ITIMN_GTE_ITINM 0x28 /* Inter-Train Min is >= Inter-Train Nom*/#define DTCAS_ERR_ITINM_GTE_ITIMX 0x29 /* Inter-Train Nom is >= Inter-Train Max*/


217

#define DTCAS_ERR_INT_PULSE_MIN 0x30 /* The Inter-Pulse Min Time cannot be 0*/#define DTCAS_ERR_IPIMN_GTE_IPINM 0x31 /* The Inter-Pulse Min is >= Inter-Pulse Nom*/#define DTCAS_ERR_IPINM_GTE_IPIMX 0x32 /* The Inter-Pulse Nom is >= Inter-Pulse Max*/#define DTCAS_ERR_PULSE_MIN 0x33 /* The Pulse Min Time cannot be 0*/#define DTCAS_ERR_PIMN_GTE_PINM 0x34 /* The Pulse Min is >= Pulse Nom*/#define DTCAS_ERR_PINM_GTE_PIMX 0x35 /* The Pulse Nom is >= Pulse Max*/#define DTCAS_ERR_PREI_LTE_PREINM 0x36 /* The Pre Interval time (min) >= Pre Interval time nom*/#define DTCAS_ERR_POSTI_LTE_POSTINM 0x37 /* The Post Interval time (min) >= Post Interval time nom */#define DTCAS_ERR_TEMPLATE_TABLE_EMPTY 0x38 /* The Template table is empty - no templates defined */#define DTCAS_ERR_EMPTY_SIGPAT_TABLE 0x39 /* Applies to a get next template command*/#define DTCAS_ERR_END_TMPL_TABLE 0x17 /* Next template was not found (1/27/2000) */#define DTCAS_ERR_SIGNAL_ENABLED 0x0f /* The signal is already enabled. */#define DTCAS_ERR_SIGNAL_NOT_ENABLED 0x3a /* Attempt to disable a signal pattern that's not enabled*/#define DTCAS_ERR_TEMPLATE_NOT_DEFINED 0x3b /* Template was not defined*/#define DTCAS_ERR_POSTINT_LTE_IPIMX 0x3c /* The Train Post-Interval is <= the inter pulse interval*/#define DTCAS_ERR_INVALID_TEMPLATE_REQ 0x3d /* Template to create is not a Seq, Train, Pulse, Transit*/#define DTCAS_ERR_PULSE_MIN_EQ_ZERO DTCAS_ERR_PULSE_MIN#define DTCAS_ERR_PULSE_NOM_EQ_ZERO 0x3f /* The Pulse time nom is zero */#define DTCAS_ERR_PULSE_MAX_EQ_ZERO 0x4a /* The Pulse time max is zero */#define DTCAS_ERR_INTR_PULSE_MIN_EQ_ZERO DTCAS_ERR_INT_PULSE_MIN /* The Inter-Pulse- interval min time is zero*/#define DTCAS_ERR_INTR_PULSE_NOM_EQ_ZERO 0x4c /* The Inter-Pulse-interval nom time is zero*/#define DTCAS_ERR_INTR_PULSE_MAX_EQ_ZERO 0x4d /* The Inter-Pulse-interval max time is zero */#define DTCAS_ERR_INTR_TRAIN_MIN_EQ_ZERO DTCAS_ERR_INT_TRAIN_MIN /* The Inter-Train- interval min time is zero*/#define DTCAS_ERR_INTR_TRAIN_NOM_EQ_ZERO 0x4f /* The Inter-Train-interval min time is zero */#define DTCAS_ERR_INTR_TRAIN_MAX_EQ_ZERO 0x5a /* The Inter-Train-interval min time is zero*/#define DTCAS_ERR_PRE_INTRV_EQ_ZERO 0x5b /* The Pre template time (really a min) is zero*/#define DTCAS_ERR_PRE_INTRV_NOM_EQ_ZERO 0x5c /* The Pre template nom time is zero */#define DTCAS_ERR_TEMPLATESENDNOTDONE 0x16 /* Sending of a template is not finished yet */#define DTCAS_ERR_INVALIDSUBCOMMAND 0x12 /* The subcommand is invalid */

#endif /* __DTICAS */


218

219

Appendix D - Related Publications

This section lists publications you should refer to for additional information oncreating digital network interface applications.

• Global Call API Programming Guide

• Global Call API Library Reference

• Voice API Programming Guide

• Voice API Library Reference

• Standard Runtime Library API Programming Guide

• Standard Runtime Library API Library Reference

• Audio Conferencing API Programming Guide

• Audio Conferencing API Library Reference

• Modular Station Interface Software Reference


220

221

Glossary

A-law: A pulse-code modulation (PCM) algorithm used in digitizingtelephone audio signals in E1 areas.

ANI: Automatic Number Identification. A feature of certaintelecommunications networking protocols or processes that allows thecaller�s phone number to be detected and displayed by the called party.

asynchronous function: On Linux platforms, a function that allowsprogram execution to continue without waiting for a task to complete.To implement an asynchronous function, an application defined eventhandler must be enabled to trap and process the completion event. Seesynchronous function.

B8ZS: Binary 8-zero Substitution. Basic bipolar coding algorithm fordigital telephony. At the transmitting end, a string of 8 zeros isdeliberately replaced with a pulse that produces a bipolar violation. Atthe receiving end, bipolar violations are replaced with a string of 8zeros.

BLT: Board Locator Technology. Operates in conjunction with a rotaryswitch to determine and set non-conflicting slot and IRQ interrupt-levelparameters, thus eliminating the need to set confusing jumpers or DIPswitches.

buffer: A block of memory or temporary storage device that holds datauntil it can be processed. It is used to compensate for the difference inthe rate of the flow of information (or time occurrence of events) whentransmitting data from one device to another.

CAS: Channel Associated Signaling. The signaling protocol used with theCEPT E1 telephony standard. In CAS, one of the 32 channels, timeslot 16, is dedicated to signaling for all of the 30 voice channels.Unlike T1 systems, which use robbed-bit signaling, telephony systemsusing CAS are considered examples of out-of-band signaling. See in-band signaling, robbed-bit signaling.

CEPT: Conference of European Postal and Telecommunicationsadministrations. Defines how bits of a PCM carrier system in E1 areaswill be used and in what sequence. CEPT format consists of 30 voice


222

channels, one signaling channel, and one framing (synchronization)channel. See E1.

CCITT: International Telephone and Telegraph Consultative Committee, apart of the ICU (International Telecommunications Union) responsiblefor formulating telephony and other standards, such as E1.

CO: Central Office. The telephone company facility where subscriberlines are linked, through switches, to other subscriber lines (includinglocal and long distance lines).

CRC: Cyclic Redundancy Check. A basic error checking mechanism fordigital transmissions in which a CRC character, indicating the numberof bits in a block of data, is included in the transmission. The receivingend calculates the number of bits in the block independently andcompares the result to the received CRC character. CRC4 is a specificalgorithm used to implement error checking.

crossover cable: A cable used to interconnect two network boards, oftento join two T1 or E1 lines. The cable is split and folded so that thelines carrying network receive data on one side of the crossoverconnector mate with network transmit lines on the other side of thecrossover.

device: A computer peripheral or component that is controlled through asoftware device driver. A digital network interface board is considereda physical board containing one or more logical board devices, andeach time slot on the board is a time slot device.

device channel: A voice data path that processes one incoming oroutgoing call at a time (equivalent to the terminal equipmentterminating a phone line). Compare time slot.

DNIS: Dialed Number Identification Service. An 800 service feature thatallows a business to determine the geographical area from which a calloriginated by the digits dialed (a different phone number is madeavailable to callers in each region).

drop-and-insert: A system configuration in which two network boardsare interconnected by a crossover cable and continuously pass all timeslots through to each other. A time slot from one network can be�dropped� to a resource module for processing. In return, the resource

Glossary

223

module can �insert� signaling and audio into the bit stream receivedfrom the other side of the crossover connector. (A resource modulecan insert only to the network board on the same side of the crossover.)This bit stream is applied through the network module for outboundtransmission to the attached network span.

E1: Another name given to the CEPT digital telephony format devised bythe CCITT. See CEPT.

E&M protocol: A signaling protocol that defines the sending andreceiving of signals. E&M protocol is the most common protocol onT1 trunks.

event: An unsolicited or asynchronous communication from a hardwaredevice to an operating system, application, or driver. Events aregenerally attention getting messages, allowing a process to decidewhen and where to redirect its resources.

event handler: A portion of an application program designed to trap andcontrol processing of device-specific events. The rules for creating adigital network interface event handler are the same as those forcreating a Linux signal handler.

Extended Attribute functions: Class of functions that take one inputparameter (a valid device handle) and return device-specificinformation. For instance, a digital network interface Linux ExtendedAttribute function returns information specific to the digital networkinterface class of devices. Extended Attribute function names are case-sensitive and must be in capital letters. See Standard Attributefunctions.

firmware: A set of program instructions that reside on an expansionboard, usually in EPROM.

fixed routing In this configuration, the resource devices (voice/fax) andnetwork interface devices are permanently coupled together in a fixedconfiguration. Only the network interface timeslot device has access tothe CT Bus. Used in DM3 architecture.

flexible routing In this configuration, the resource devices (voice/fax) andnetwork interface devices are independent, which allows exporting andsharing of the resources. All resources have access to the CT Bus. Usedin DM3 architecture.


224

in-band signaling: 1. In an analog telephony circuit, in-band refers tosignaling that occupies the same transmission path and frequency bandused to transmit voice tones. 2. In digital telephony, �in-band� hascome to mean signaling that is transmitted within an 8-bit voice sampleor time slot, as in T1 �robbed-bit� signaling.

IRQ: Interrupt request. A signal sent to the central processing unit (CPU)to temporarily suspend normal processing and transfer control to aninterrupt handling routine. Interrupts may be generated by conditionssuch as completion of an I/O process, detection of hardware failure,power failures, etc.

mu-lawMu-LAW: 1. A pulse code modulation (PCM) algorithm used indigitizing telephone audio signals in T1 areas. 2. The PCM coding andcompounding standard used in Japan and North America.

PSTN: Public Switched Telephone Network

robbed-bit signaling: The type of signaling protocol implemented inareas using the T1 telephony standard. In robbed-bit signaling,signaling information is carried in-band, within the 8-bit voice samples.These bits are later stripped away, or �robbed,� to produce thesignaling information for each of the 24 time slots. See CAS, in-bandsignaling.

route: Assign a resource to a time slot.

SCbus: Signal Computing bus. The TDM (Time Division Multiplexed)resource sharing bus that allows information to be transmitted anreceived among resources over multiple data lines. A hardwiredconnection between Switch Handlers on SCbus based products fortransmitting information over 1024 time slots to all devices connectedto the SCbus.

SCSA: Signal Computing System Architecture

Signal Computer System Architecture: SCSA. A standard opendevelopment platform. An open hardware and software standard thatincorporates virtually every other standard in PC-based switching. Allsignaling is out of band. In addition, SCSA offers time slot bundlingand allows for scalability.

Glossary

225

signaling insertion: Mode in which the digital network interface (or anynetwork board) overwrites signaling data from resource modules inorder to perform signaling to the network.

SRL: Standard Runtime Library. A software resource containing EventManagement functions, Standard Attribute functions, and datastructures used by all devices, but which return data unique to thedevice.

Standard Attribute functions: Class of functions that take one inputparameter (a valid device handle) and return generic information aboutthe device. For instance, Standard Attribute functions return IRQ anderror information for all device types. Standard Attribute functionnames are case-sensitive and must be in capital letters. StandardAttribute functions for all devices are contained in the SRL. SeeExtended Attribute functions.

synchronous function: On Linux platforms, a function that blocksprogram execution until a value is returned by the device. Also calleda blocking function. See asynchronous function.

time slot: In a digital telephony environment, a normally continuous andindividual communication (for example, someone speaking on atelephone) is (1) digitized, (2) broken up into pieces consisting of afixed number of bits, (3) combined with pieces of other individualcommunications in a regularly repeating, timed sequence(multiplexed), and (4) transmitted serially over a single telephone line.Each individual digitized communication is called a time slot. In T1areas, 24 time slots are multiplexed onto a single twisted-wire pair. InE1 areas, 32 time slots are multiplexed together. Compare devicechannel.

time slot assignment: The ability to route the digital informationcontained in a time slot to a specific device channel. See devicechannel.


226

wink: In T1 or E1 systems, a signaling bit transition from on to off, or offto on, and back again to the original state. In T1 systems, the winksignal can be transmitted on either the A or B signaling bit. In E1systems, the wink signal can be transmitted on either the A, B, C, or Dsignaling bit. Using either system, the choice of signaling bit and winkpolarity (on-off-on or off-on-off hook) is configurable through digitalnetwork interface board download parameters.

227

Index

Aaborting an application, 175

advanced features, 176

Agent automation, 3

alarmtransmission to network, 152

Alarm functions, 22

alarm handling, 163E1, 5hardware alarm indicators, 19

alarms, layer 1, 178

asynchronous, 80

asynchronous mode, 21

Audiotex, 3

Bbackward compatibility, 4

billing automationSee Operator services, 3

blue alarm, 17

CCAS, 13

Cellular messaging, 3

Central-office-based voice mailSee CO-based voice mail, 3

CEPT, 13

Channel Associated SignalingSee CAS, 13

closing devices, 78

compiling, 175

DD4 superframe, 8

D4 frame, 8

device handle, 112

device parameter, 129

device parametersSee dt_getparm( ), 98

Diagnostic functions, 22

diagnostics, 115testing communications, 141testing I/O interface, 145

dialing, 4

Direct dial-in (DDI) service, 3

directory assistanceSee Operator services, 3

distant multiframe alarm, 18

drop-and-insert configuration, 3

DS-0, 7

DS-1, 7

dt_getctinfo( ), 85

dt_getevtmsk( ), 179

dt_getxmitslot( ), 105

dt_listen( ), 108

dt_setevtmsk( ), 178

dt_unlisten( ), 149


228

dtilib.h, 29

EE&M, 10

E1 frame, 10

EPROMSee ATDT_ROMVER( ), 47version, 47

event mask, 93values, 95

eventsevent bitmask

See event mask, 93event management, 3

Extended Attribute functions, 23

Ffirmware

See ATDT_DNLDVER( ), 39version, 39

functiondt_getctinfo( ), 85dt_getxmitslot( ), 105dt_listen( ), 108dt_unlisten( ), 149

function librarySee also Voice library, 4

functions supportednetwork interface library, 177

Hhardware compatibility

backward compatibility, 4

hardware configuration, 162

header files, 159

Iidle state

See ATDT_IDLEST( ), 44

idling, 126

include files, 159

initialize time slots, 164

intercept treatmentsSee Operator services, 3

Llayer 1 alarms, DTI Network Interface,

178

LEDs, 19

linking, 175

Nnetwork interface library

supported functions, 177

Oopening time slots, 4

Operator services, 3

PParameter Request functions, 23

Parameter Setting functions, 23

Rred alarm, 17

remote alarm, 18

Resource Management functions, 24

robbed-bit signaling, 9

Index

229

SSC_TSINFO, 109

SCbusrouting, 16routing functions, 24terminology, 5

SCbus routing functions, 24

Service bureaus, 3

signalingE1 national/international bits, 15mode, 32See ATDT_BDMODE( ), 32T1, 9

signaling all 1s alarm, 18

signaling bits, 138See ATDT_TSSGBIT( ), 58transmit, 135

signaling insertion mode, 132

signaling modeSee ATDT_TSMODE( ), 55

silence, 126

SRL, 3, 23

Standard Attribute functionsSee SRL, 23

Standard Runtime Librarysee SRL, 3

supported functionsnetwork interface library, 177

synchronizationT1, 9

synchronous, 141

synchronous mode, 21

TTelemarketing, 3

terminate configuration, 3

tests, 141, 145

time division multiplexing, 8

time slotsignaling bits, 58signaling mode, 55

Time Slot Audio functions, 25

Time Slot Signaling functions, 25

time slot statusSee ATDT_STATUS, 52

transparent signaling mode, 5See also signaling mode, 5

Uunframed all 1s alarm, 18

VVoice library, 4

Wwink signaling, 155

Yyellow alarm, 17

Documents

Digital Network Interface Software Reference1. Prepare the digital network interface board for installation using the appropriate hardware installation card (see Appendix D - Related