You are here: CSP API Reference > 1 EXS & SwitchKit API Messages > Collect Digit String 0x00BC

Collect Digit String 0x00BC

SwitchKit Name

CollectDigitString

Type

EXS API and SwitchKit API message

Description

This message instructs the Excel platform to attach a digit receiver to the specified channel.

NOTE: The digit receiver collects digit strings only if the digits are either DTMF or MFR1, or if the call is in a state other than idle, out of service, or busied out

Once the receiver has collected the digits, the Excel platform sends a Call Processing Event message with the value 0x02 (Digits) in the Call Processing Event field. If an error occurs, the Excel platform sends a Call Processing Event message and indicates the error using the Status field.

If the host sends this message and specifies a channel to which a digit receiver is already attached, the Excel platform sends the host a response with a status of 0x30 (DSP Resource Already Allocated). The channel is not affected.

The Excel platform releases the digit receiver from the channel when one of the following occurs:

• The Excel platform sends a Call Processing Event message

• The call is released

• The Excel platform receives a DSP Service Cancel message from the host

Sent by

Host Application

SwitchKit Code

C Structure

typedef struct {

unsigned short Span;

UBYTE Channel;

UBYTE Mode;

UBYTE MaxDigits;

UBYTE NumTermChars;

UBYTE ConfigBits;

unsigned short TermChars;

unsigned short InterDigitTimer;

unsigned short FirstDigitTimer;

unsigned short CompletionTimer;

unsigned short MinReceiveDigitDuration;

UBYTE AddressSignallingType;

UBYTE NumDigitStrings;

unsigned short ResumeDigitCltnTimer;

} XL_CollectDigitString;

C++ Class

class XLC_CollectDigitString : public XLC_OneChannelOutbound {

public:

unsigned short getSpan() const;

void setSpan(unsigned short x);

UBYTE getChannel() const;

void setChannel(UBYTE x);

UBYTE getMode() const;

void setMode(UBYTE x);

UBYTE getMaxDigits() const;

void setMaxDigits(UBYTE x);

UBYTE getNumTermChars() const;

void setNumTermChars(UBYTE x);

UBYTE getConfigBits() const;

void setConfigBits(UBYTE x);

unsigned short getTermChars() const;

void setTermChars(unsigned short x);

unsigned short getInterDigitTimer() const;

void setInterDigitTimer(unsigned short x);

unsigned short getFirstDigitTimer() const;

void setFirstDigitTimer(unsigned short x);

unsigned short getCompletionTimer() const;

void setCompletionTimer(unsigned short x);

unsigned short getMinReceiveDigitDuration() const;

void setMinReceiveDigitDuration(unsigned short x);

UBYTE getAddressSignallingType() const;

void setAddressSignallingType(UBYTE x);

UBYTE getNumDigitStrings() const;

void setNumDigitStrings(UBYTE x);

unsigned short getResumeDigitCltnTimer() const;

void setResumeDigitCltnTimer(unsigned short x);

};

 

Overview of message

The following table provides an overview of this message. The table following it provides the detail for each byte.

MESSAGE (White)

RESPONSE (Gray)

Byte

Field Description

Byte

Field Description

0

Frame (0xFE)

0

Frame (0xFE)

1, 2

Length (0xNNNN)

1, 2

Length (0x0005)

3, 4

Message Type (0x00BC)

3, 4

Message Type (0x00BC)

5

Reserved (0x00)

5

Reserved (0x00)

6

Sequence Number

6

Same Sequence Number

7

Logical Node ID

7

Logical Node ID

:

AIB (Starting with byte 0)

8, 9

Status (MSB, LSB)

0x0002 DSP Receiver Request Timeout

10

Checksum

:

Mode

:

Max Digits

:

Number of Terminating Characters

:

Configuration Bits

:

Terminating Characters (MSB, LSB)

:

Interdigit Timer (MSB, LSB)

:

First Digit Timer (MSB, LSB)

:

Completion Timer (MSB, LSB)

:

Minimum Receive Digit Duration Timer (MSB, LSB)

:

Address Signaling Type

:

Number of Digit Strings

:

Resume Digit Collection Timer (MSB, LSB)

:

Checksum

 

Hex API Format - Detailed

MESSAGE (White)

RESPONSE (Gray)

Byte

Field Description

Byte

Field Description

0

Frame (0xFE)

0

Frame (0xFE)

1, 2

Length 0xNNNN

1, 2

Length 0xNNNN

3, 4

Message Type (0x00BC)

3, 4

Message Type (0x00BC)

5

Reserved (0x00)

5

Reserved (0x00)

6

Sequence Number

6

Same Sequence Number

7

Logical Node ID

7

Logical Node ID

:

AIB

Address Method

0x00 - Individual AEs

8, 9

Status MSB, LSB

10

Checksum

Number of AEs to follow

AE

0x0D Channel

:

Mode

0x01 Fixed Number of Digits

0x02 Use Terminating Characters

0x03 Use KP_ST Characters

0x04 Use Fixed Number of Digits or Terminating Characters

0x05 Reserved

0x06 Reserved

0x07 Reserved

0x08 Fixed or Indefinite Number of Digits

 

If the first digit detected is zero, the Indefinite Number of Digits method is used and the Completion Timer or Interdigit Timer is used (whichever expires first) to terminate digit collection. If the first digit collected is not zero, the Fixed Number of Digits method is used.

This method is used to help facilitate collecting digit strings on channels that process national and international calls.

:

Max Digits

Maximum number of digits to collect (0–100)

This field is valid only if the Mode field value is either 0x01 (Fixed Number of Digits)
or 0x04 (Use Fixed Number of Digits or Term Chars); otherwise, it is ignored.

:

Number of Terminating Characters

Number of terminating characters to collect (0–4).

This field is valid only if the Mode field value is either 0x02 (Use Terminating Characters)
or 0x04 (Use Fixed Number of Digits or Term Chars); otherwise, it must be 0x00.

:

Configuration Bits

Bit

0 Report Digit at Falling Edge

0 Digit is reported at its rising edge when the digit is first pressed or if it is present
on the line at the time the receiver is attached.

1 Digit is reported at its falling edge when the digit is first released.

1 First Digit Collected

0 Do not inform the host that the first digit was collected.

1 Inform the host that the first digit was collected. Use the Call Processing Event
message. The first digit will also be reported in the Call Processing Event
message with the remaining digits.

 

2 Ignore # Character

0 Do not ignore the "#" character as the first digit.

1 Ignore the "#" character as the first digit.

3 Suspend Digit Collection

0 Do not suspend digit collection.

1 Suspend digit collection upon outpulsing digits.

 

The following requires that one DSP-ONE or MFDSP card be configured with both DTMF
Transmission and DTMF Reception. Channels with this feature enabled will only have
access to DTMF Receivers on cards which also have DTMF Transmitters configured.

 

4 Cancel Prompting Tone or Recorded Announcement

0 Prompting tone or RAN is cancelled on receipt of the first digit.

1 Prompting tone or recorded announcement continues.

 

5 Detect Leading Silence (only used for rising edge detection)

0 Do not require leading silence before reporting valid rising edge

digit.

1 Require detection of leading silence before reporting the first valid

rising edge digit. Digits on the line at time of receiver attachment

will not be reported.

 

6 Cancel Recording

0 Recording is cancelled on receipt of the first digit

1 Recording continues

 

7 Reserved, must be 0.

:

Terminating Characters MSB, LSB

Use this two-byte field only if the value of the Mode field is either 0x02 (Use Terminating
Characters) or 0x04 (Use Fixed Number of Digits or Term Chars). The terminating
characters are stored as nibbles. You can define up to four terminating characters,
as shown below.


MSB

Bit

0–3 Terminating Character 2

4–7 Terminating Character 1


LSB

Bit

0–3 Terminating Character 4

4–7 Terminating Character 3

:

Interdigit Timer MSB, LSB

NOTE: Timers are in 10 ms units.

The maximum time to wait between digits after the first one is received.
The value 0xFFFF disables this timer.

:

First Digit Timer MSB, LSB

The maximum time to wait for the first digit of a string (in 10 ms units).
The value 0xFFFF disables this timer.

:

Completion Timer MSB, LSB

The maximum time to wait for the entire string after the first digit is detected.
The value 0xFFFF disables this timer.

:

Minimum Receive Digit Duration Timer MSB, LSB

The minimum time a digit must be detected before it is declared valid.
The value must be at least 30 ms, which is the default.

:

Address Signaling Type

The address signaling type must be the same for both strings within a stage,
but may differ between stages.

0x01 DTMF

0x02 MFR1

:

Number of Digit Strings

Number of digit strings to collect (1 or 2, usually 1 unless strings are KP/ST framed)

:

Resume Digit Collection Timer MSB, LSB

The amount of time to wait after outpulsing is complete to resume digit collection.

:

Checksum