You are here: CSP API Reference > 1 EXS & SwitchKit API Messages > PPL Table Download 0x00D6

PPL Table Download 0x00D6

SwitchKit Name

PPLTableDownload

Type

EXS API and SwitchKit API message

Description

PPL Table Download 0x00D6

Use this message to download PPL tables that are subsequently used to create a PPL protocol.

Before using this message, the host must first establish the table to be downloaded using the PPL Table Initiate Download message. The PPL Table Download message is then used to pass the table data to the CSP.

If the table data exceeds the maximum length allowed for one message, you will have to use more than one of these messages. You must send them sequentially because the CSP maintains the offset into the table on successive commands.

Sent by

Host

SwitchKit Code

C Structure

typedef struct {

unsigned short ComponentID;

UBYTE TableType;

UBYTE TableID;

UBYTE Data[249];

} XL_PPLTableDownload;

C Structure Response

typedef struct {

unsigned short Status;

UBYTE DataSize;

UBYTE ErrorType;

UBYTE Data[250];

} XL_PPLTableDownloadAck;

C++ Class

class XLC_PPLTableDownload : public XLC_OutboundMessage {

public:

unsigned short getComponentID() const;

void setComponentID(unsigned short x);

UBYTE getTableType() const;

void setTableType(UBYTE x);

UBYTE getTableID() const;

void setTableID(UBYTE x);

const UBYTE *getData() const;

UBYTE *getData();

void setData(UBYTE *x);

};

C++ Class Response

class XLC_PPLTableDownloadAck : public XLC_AcknowledgeMessage {

public:

unsigned short getStatus() const;

void setStatus(unsigned short x);

UBYTE getDataSize() const;

void setDataSize(UBYTE x);

UBYTE getErrorType() const ;

void setErrorType(UBYTE x);

const UBYTE *getData() const;

UBYTE *getData();

void setData(UBYTE *x);

};

EXS API Hex Format

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 (0x00D6) | 3, 4 | Message Type (0x00D6)
5 | Reserved (0x00) | 5 | Reserved (0x00)
6 | Sequence Number | 6 | Same Sequence Number
7 | Logical Node ID | 7 | Logical Node ID
8, 9 | PPL Component ID MSB, LSB See PPL Component IDs in the API Reference. | 8, 9 | Status MSB, LSB
10 | Table Type (see formats below) 0x01 Primitive Table 0x02 Basic State/Event Table 0x03 Route Table 0x04 Resource Group Table 0x07 Extended State/Event Table | : | The following bytes apply if the Status is a NACK: "Table Does Not Validate" (0xA9). Otherwise, this field is 0x00, followed by the checksum. Error Data Length: The number of bytes of data to follow, including the Error Type field.
11 | Table ID Number assigned to table by host 0x01–0x0A | : | Error Type: General Errors 0x01 Invalid Table Type 0x02 Invalid Checksum Primitive Table Errors 0x03 Invalid Number of Atomic Functions In Primitive 0x04 Invalid Atomic Function ID 0x05 Invalid Primitive Table Size State/Event Table Errors 0x06 Invalid Number of Events per State 0x07 Invalid Event ID (Exceeds Allowable Range) 0x08 Invalid Next State Type 0x09 Invalid State/Event Table Size Router Errors 0x0A Invalid route number 0x0B Invalid criteria type 0x0C Null TLV Resource Group Errors 0x0D Invalid number of AIBs in Resource Group 0x0E Invalid AIB in Resource Group 0x0F Incorrect number of address elements in Resource More Router Errors 0x10 Router Table Full 0x11 Router Table validation error 0x0A Invalid route number 0x0B Invalid criteria type 0x0C Null TLV 0x0D Invalid number of AIBs in Resource Group 0x0D Invalid AIB in Resource Group 0x0F Incorrect number of address elements in Resource Group 0x10 Router Table Full 0x11 Router Table validation error 0x12 Invalid Route Group Id for Criteria
12 | Table Data - See tables below this one. | : | Error Data[0] The data is dependent on the value on the Error Type field. (0x01) Invalid Table Type Reported via a Status code. (0x02) Invalid Checksum Bytes 0–3 Checksum (0x03) Invalid Number Of Atomic Functions Bytes 0, 1 Primitive ID Byte 2 Number of Atomic Functions (0x04) Invalid Atomic Function ID Bytes 0, 1 Primitive ID Bytes 2, 3 Atomic Function ID (0x05) Invalid Primitive Table Size Bytes 0, 1 Primitive ID Bytes 2 Number of Atomic Functions (0x06) Invalid Number of Events Per State Bytes 0, 1 State ID Bytes 2, 3 Number of events (0x07) Invalid Event ID Bytes 0, 1 State ID Bytes 2, 3 Event ID (0x08) Invalid Next State Type Bytes 0, 1 State ID Byte 2 Next State Type (0x09) Invalid State/Event Table Size Bytes 0, 1 State ID Bytes 2, 3 Number of Events
|  |  | (0x0A) Invalid route number Bytes 0, 1 Route Number (0x0B) Invalid criteria type Bytes 0, 1 Entry Data TLV Count (0x0C) Null TLV Bytes 0, 1 Entry Data TLV Count (0x0D) Invalid number of AIBs in Resource Group Bytes 0, 1 Resource Group ID (0x0E) Invalid AIB in Resource Group Bytes 0, 1 Resource Group ID (0x0F) Incorrect number of address elements in Resource Bytes 0, 1 Resource Group ID (0x10) Router Table Full Byte 0 Reserved Byte 1 Table ID (0x11) Router Table validation error Byte 0 Reserved Byte 1 Table ID (0x12) Invalid Route Group Id for Criteria Byte 0 Reserved
N + 3 | Checksum | N+3 | Checksum

Primitive Table Format (0x01)

A Primitive Table is a set of primitives used in conjunction with a State/Event Table to create a PPL protocol. Each Primitive Table can contain up to 400 primitives. The Primitive Table is assigned to the protocol when the protocol is created with the PPL Create message.

The Primitive Table format is shown in the table below.

Byte | Field Description | Definition
Message Header
8, 9 | PPL Component ID (MSB, LSB) | See list of Component IDs in this document.
10 | Table Type | 0x01 Primitive Table
11 | Table ID | Assigned by host.
Table Data
12, 13 | Data[0,1] Primitive ID (MSB, LSB) | Identifies each primitive in the primitive table. Each primitive in the table must be unique, and in the range from 0 to 199. The primitives in the table must be ordered lowest number to highest (numbers may be skipped).
14 | Data[2] Number of AFs | The number of AFs used to create the primitive (1 to 10).
15, 16 | Data[3,4] AF: ID (MSB, LSB) | The AF ID specifies the predefined function to be invoked (in the range supplied by Dialogic ).
17, 18 | Data[5,6] Arg 1 Value (MSB, LSB) | The first argument value to pass to the AF.
19, 20 | Data[7,8] Arg 2 Value (MSB, LSB) | The second argument value to pass to the AF.
Repeat Data[3-8] for each AF in the primitive.
: | Checksum |

Basic State/Event Table Format (0x02)

A Basic State/Event table is a group of valid events that pertain to a given state, the primitives that get invoked upon the occurrence the event, and the next state to transition into in response to the event(s). State/event tables allow for up to 100 states and up to 20 events per state. The Primitive Table is assigned to the protocol when the protocol is created with the PPL Create message.

The Basic State/Event Table format is shown in the table below.

Byte | Field Description | Definition
Message Header
8, 9 | PPL Component ID (MSB, LSB) | See list of Component IDs in this document.
10 | Table Type | 0x02 Basic State/Event Table
11 | Table ID | Assigned by host
Table Data
12 | Data[0] Table Data Initial State Number | Identifies the current state that the protocol is in. States must be specified in order from 1 to 199. State numbers can be skipped. The initial State Type is assumed to be Normal.
13 | Data[1] Number of Events | The number of valid events accepted by the state. Each state can accept up to 120 events. For best performance, events most likely to occur should be placed at the beginning of the list.
14, 15 | Data[2, 3] Event 1 # (MSB, LSB) | See the for event data.
16, 17 | Data[4, 5] Event Data 1 Value (MSB, LSB)
18, 19 | Data[6, 7] Event Data 2 Value (MSB, LSB)
20, 21 | Data[8, 9] Primitive ID (MSB, LSB) | The primitive invoked when the specified event occurs based on the Primitive Table associated with the event.
22 | Data[10] Next State Number | The state that the protocol should enter in response to the indicated event(s).
23 | Data[11] Next State Type | 0x01 Normal/Wait 0x02 Internal
Repeat Data[2-11] for each event associated with the state.
: | Checksum |

Route Table (0x03)

The Route Table format is shown in the table below.

Byte | Field Description | Definition
Message Header
8, 9 | PPL Component ID (MSB, LSB) | See PPL Information chapter in API Reference.
10 | Table Type | 0x03 Route Table
11 | Table ID | Assigned by host
Table Data
12, 13 | Data[0, 1] Route Number | Index into the Route Table
14 | Data[2] Route Property | This field is a bit mask indicating the details about the format of the remaining message bytes. Bit 0-4 Not used 5 Force the storage of entry in Sequential Linked List. If not set, use the default method of storage. 6 If set, use exact matching. If cleared use default method of matching 7 Version of Route Table. Should always be set.
15 | Data[3] Route Property - Addressing method | This field is a bit mask indicating the addressing method, either single or range. Bit 0 Single 1 Range
16, 17 | Data[2, 3] Version | Currently version 0x0001.
18, 19 | Data[4, 5] Route Group ID | A grouping of routes based on a defined criteria or other information.
20, 21 | Data[6, 7] Route Criteria Type. See Route Criteria Type entries below. | Identifies the type of information defining the route.
22 | Data[8] Criteria Data: Format | 0x01 Data in raw hex bytes 0x03 BCD (All digit based routes are BCD.)
23, 24 | Data[9, 10] Criteria Data: Length of Criteria Data |
25 | Data[11..N] Criteria Data | See Route Criteria Type entries below for the definition of remaining data.
: | Data[N+0, N+1] Entry Data TLV Count | 2 Bytes
: | Data[N+2, N+3] Entry Data TLV Length | 2 Bytes
: | Data[N+4] Entry Data: TLVs | See Route Entry Data TLV entries below.
: | Checksum |

Route Criteria Type entries

0x0007 Incoming Span/Channel, Single/Range

0x0009 Terminating Span/Channel, Single/Range

0x0010 Incoming Resource Group, Single/Range

0x0015 Terminating Resource Group, Single/Range

0x0065 Physical VoIP Channel

0x0071 Virtual VoIP Channel

0x03E9 User-defined

NOTE: See Notes 1, 2 and 3 below to configure the following Route Criteria Type entries.

0x2710 Universal Protocol Data, Single/Range

0x2717 Called Party Number, Single/Range

0x2718 Calling Party Number, Single/Range

0x2792 Source IP Address, Single/Range

0x2794 Destination IP Address, Single/Range

0x27B0 RTP Payload Type, Single/Range

0x27B4 IP Address Criteria, Single/Range

0x2919 NPDI SIP to Username, Single/Range

0x291A NPDI SIP to Hostname, Single/Range

0x2919 NPDI SIP from Username, Single/Range

0x291A NPDI SIP from Hostname, Single/Range

0x2A0E Media Connection Address, Single/Range

Notes

1. The second data format field that occurs after the length can have the following values:

• 0x01 - Data in Raw Hex Bytes

• 0x02 - ASCII Characters

• 0x03 - BCD (all digit-based routes are BCD)

• 0x04 - Decimal

2. The length of the this field is variable. It is equal to the Criteria Length minus the length of the Criteria Header information (for example, all fields after the length and not including the digits and mask fields) divided by the number of digits and mask fields included.

Below is an example of how the Single bit in the Route Property Mask is set (see field 15 in Route Table (0x03) above).

To compute the Length of Field which is equal to 7, do the following:

Criteria Length (20) subtract (-) Length of Criteria Header (6) and divide (/) by number of Digit and Mask fields (2)

2a 0e \ ' Media Connection Criteria Type

03 \' Criteria Data Format: BCD

00 14 \ ' Length

03 \ 'Criteria Data Format: BCD

63 \ ' Offset

00 00 00 00 \ ' Reserved - set to 0x00 0x00 0x00 0x00

04 05 05 06 06 07 08 \ ' Digits string

0f 0f 0f 0f 0f 0f 0f \ ' Mask

Below is an example of how the Range bit in the Route Property Mask is set (see field 15 in Route Table (0x03) above).

To compute the Length of Field which is equal to 1, do the following:

Criteria Length (9) subtract (-) Length of Criteria Header (6) and divide (/) by number of Digit and Mask fields (3)

2a 0e \ ' Media Connection Criteria Type

01 \ ' Criteria Data Format

00 09 \ ' Length

04 \ ' Criteria Data Format: Decimal

2c \ ' Offset

00 00 00 00 \ ' Reserved

0a \ ' From digits

cd \ ' To digits

ff \ ' Mask

3. The Offset field represents the number of channels to offset outgoing channel from incoming channel.

Route Entry TLV Type entries

0x0009 Address Element Blocks

0x0015 Resource Group ID

0x0062 Resource Group Reorder Method

0x0063 Route Number

0x001B Resource Table ID

0x001C Route Table ID

0x0161 PAD Values

0x03E9 User-defined

Resource Group Table (0x04)

The format of the Resource Group Table is shown in the table below.

Byte | Field Description | Definition
Message Header
8, 9 | PPL Component ID (MSB, LSB) | See PPL Information chapter in API Reference.
10 | Table Type | 0x04 Resource Group Table
11 | Table ID | Assigned by host
Table Data
12, 13 | Data[0, 1] Resource Group ID |
14, 15 | Data[2, 3] Special Instructions | 0x0001
16, 17 | Data[4, 5] | Version Number should be 0x0001
18, 19 | Data[6, 7] Number of AIBs |
20, 21 | Data[8, 9] Length of AIBs |
22+ | Data[:] AIB | See AIB Types
: | Data[:] Number of TLVs | The number of Tag/Length/Value entries to follow.
: | Data[:] Length of TLVs |
: | Data[:] TLVs | See TLV Types
: | Checksum |

Extended State/Event Table Format (0x07)

An Extended State/Event table is a group of valid events that pertain to a given state, the primitives that get invoked upon the occurrence the event, and the next state to transition into in response to the event(s). State/event tables allow for up to 100 states and up to 20 events per state. The Primitive Table is assigned to the protocol when the protocol is created with the PPL Create message.

The Extended State/Event Table format is shown in the table below.

Byte | Field Description | Definition
Message Header
8, 9 | PPL Component ID (MSB, LSB) | See list of Component IDs in this document.
10 | Table Type | 0x07 Extended State/Event Table
11 | Table ID | Assigned by host
Table Data
12 | Data[0,1] Initial State Number | Identifies the current state that the protocol is in. States must be specified in order from 1 to 199. State numbers can be skipped. The initial State Type is assumed to be Normal.
13 | Data[2] Number of Events | The number of valid events accepted by the state. Each state can accept up to 120 events. For best performance, events most likely to occur should be placed at the beginning of the list.
14, 15 | Data[3,4] Event 1 # (MSB, LSB) | Bytes 14 and 15 are external processing events, such as, Alerting or Answer; or internal decision events. Bytes 16-19 are arguments that relate to events such as, filter timer IDs for line signaling events. See the API Developer’s Guide: PPL for more details.
16, 17 | Data[5, 6] Event Data 1 Value (MSB, LSB)
18, 19 | Data[7, 8] Event Data 2 Value (MSB, LSB)
20, 21 | Data[9, 10] Primitive ID (MSB, LSB) | The primitive invoked when the specified event occurs based on the Primitive Table associated with the event.
22 | Data[11, 12] Next State Number | The state that the protocol should enter in response to the indicated event(s).
23 | Data[13] Next State Type | 0x01 Normal/Wait 0x02 Internal
Repeat Data[2-13] for each event associated with the state.
: | Checksum |

See Programmable Protocol Language.
A computer, attached to the Excel platform through an RS-232 or Ethernet link, from which you run the telecommunications application that controls the Excel platform.
A group of data bits in a specific format, with a flag at each end to indicate the beginning and the end of the frame.
A programmable software component that uses PPL state machines that can be modified with the PPL Tool.
Most Significant Bit
Least Significant Bit
Group of one or more Atomic Functions that allow multiple actions (tests) to be initiated in response to a PPL event for a channel. See Programmable Protocol Language.
The condition of a component at a given instant. The current "context" of a PPL object, such as Idle, Seizing, Answered. In PPL files, a State is represented by a circle.
Negative acknowledgement to a message.
AF. A predefined PPL software routine that performs a single, simple task, such as "Transmit Line Signaling" or "Allocate Digit Buffer." It is composed of standard software interrupts, calls, and data formats used by applications. Each AF has two values named "Arguments." AFs 1-50 are generic, and apply to all PPL components. AFs 51 and above apply to specific components. An AF is called "Atomic" because it is the smallest useful unit in PPL.
Tag-Length-Value block. A standardized block that allows data to inserted in a standard way into API messages.
See Address Information Block.
See Atomic Function.
In PPL, a condition that, when met, drives a state machine (PPL Component) from one state to another, by invoking an associated Primitive. In PPL files, an Event is marked by an arrow and text.
Notation that describes line card redundancy, where N is the number of installed line cards of a single card type and 1 is an additional line card of that type designated as a standby card. For example, if you have three T-ONE cards and one additional standby T-ONE card installed, the system provides redundancy by activating the standby card if any of the three active T-ONE cards fail.
Range of channels provided by T1 or E1 transmission service. A physical span is a group of channels taking up a single physical wire. A logical span is a group of channels taking up less than a single logical wire, or carried over more than one physical wire.
Voice over Internet Protocol. The delivery of voice information in digital form in discrete packets rather than in the traditional circuit-committed protocols of the public-switched telephone network (PSTN).
Internet Protocol. Part of the TCP/IP family of protocols used to route messages and tracks the addresses of nodes.
A 32-bit address, used in IP routing, which includes a Network address identifier assigned by a central authority and a Host ID (an end station identifier assigned by a LAN administrator).
Real-Time Transport Protocol. Supports transport of real-time data like interactive voice and video over packet-switched networks.
Network Protocol Data Intelligence. Also called “Interworking,” it is a software product that operates within Excel’s Call Control (Layer 4) and Services (Layer 5) call processing layers. NPDI is meant to enhance Excel’s call processing product offering by allowing call processing layers (specifically Layers 4 and 5) to perform advanced analysis, generation, and conversion of Network Signaling (NS) Layer 3 information.
Session-Initiation Protocol. A signaling protocol used for establishing sessions in an IP network. A session could be a simple, two-way telephone call, or it could be a collaborative multi-media conference session.
American Standard Code for Information Interchange
The information in an AIB that follows the header, down to the data field. An AIB can have one or more Address Elements. AEs correspond to Span, Channel, and SS7 Link.
Packet Assembler/Disassembler