You are here: CSP API Reference > 1 EXS & SwitchKit API Messages > PPL Protocol Query 0x00DF
SwitchKit Name
PPLProtocolQuery
Type
EXS API and SwitchKit API message
Description
This message initiates a report from the Excel platform on the custom protocols (non-default) that have been downloaded to a PPL component. There are two methods.
The first indicates every table downloaded to a particular PPL component and its associated protocols, if any. This is Sent by setting the Entity field to 0x00 (All Tables).
The second indicates the name of a particular entity (table or protocol). This is initiated by setting the Entity field to either 0x01 (Primitive Table), 0x02 (State/Event Table), or 0x03 (Protocol), and specifying the ID in the Entity ID field.
Sent by
SwitchKit Code
C Structure
typedef struct {
unsigned short ComponentID;
UBYTE Entity;
UBYTE EntityID;
} XL_PPLProtocolQuery;
C Structure Response
typedef struct {
unsigned short Status;
unsigned short ComponentID;
UBYTE Entity;
UBYTE EntityID;
UBYTE Data[247];
} XL_PPLProtocolQueryAck;
C++ Class
class XLC_PPLProtocolQuery : public XLC_OutboundMessage {
public:
unsigned short getComponentID() const;
void setComponentID(unsigned short x);
UBYTE getEntity() const;
void setEntity(UBYTE x);
UBYTE getEntityID() const;
void setEntityID(UBYTE x);
};
C++ Class Response
class XLC_PPLProtocolQueryAck : public XLC_AcknowledgeMessage {
public:
unsigned short getStatus() const;
void setStatus(unsigned short x);
unsigned short getComponentID() const;
void setComponentID(unsigned short x);
UBYTE getEntity() const;
void setEntity(UBYTE x);
UBYTE getEntityID() const;
void setEntityID(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 (0x0007) |
|
3, 4 |
Message Type (0x00DF) |
3, 4 |
Message Type (0x00DF) |
|
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 |
Entity 0x00 All Tables 0x01 Primitive Table 0x02 State/Event Table 0x03 Protocol 0x07 Extended State/Event Table |
10, 11 |
PPL Component ID MSB, LSB See PPL Component IDs in the API Reference. |
|
11 |
Entity ID The ID of the table or protocol to be queried. If the Entity is All Tables (0x00) set this field to 0x00. |
12 |
Entity |
|
12 |
Checksum |
13 |
Entity ID |
|
|
Response continued below. |
||
|
14 |
Data[0] The data varies by the Entity being queried.
0x00 All Tables Data[0] Number of Tables Data[1] Table Type 0x01 Primitive Table 0x02 State/Event Table 0x07 Extended State/Event Table Data[2]* Table ID (1-10) Data[3]* Associated Protocol (0xFF if none)
Data[1–3] is repeated for each table
All Others: Data[0] Entity Name A NULL-terminated ASCII string of up to 20 characters describing the protocol |
||
|
: |
Checksum |
||
Examples
Assumptions
• Component: 0x12
• Downloaded Protocols
02 cpc_CPG_T7
• Primitive Tables
02 isup_cpc_itu_ppl_pr
• State Event Tables
02 isup_cpc_itu_ppl_st
Query All Tables
Message
To query all tables, you would send the message as shown below, with the following values:
• Component ID: 00 12
• Entity: All Tables (00)
• Entity ID: 00
H->X
[00 09 00 df 00 00 ff 00 12 00 00]
Response
The Excel platform returns the following bytes indicating that component 12 has 2 tables:
• Primitive Table 02 (Protocol 2)
• State Event Table 02 (Protocol 2)
X->H
[00 12 00 df 00 00 01 00 10 00 12 00 00 02 01 02 02 02 02 02]
Query Primitive Table
Message
To retrieve the name of Primitive Table 2, you would send the following bytes:
• Entity 01 (Primitive Table)
• Entity ID 02
H->X
[00 09 00 df 00 00 ff 00 12 01 02]
Response
The Excel Platform responds with a string of ASCII characters indicating the protocol name: isup_cpc_itu_ppl_pr
X->H
[00 1f 00 df 00 00 01 00 10 00 12 01 02 69 73 75 70 5f 63 70 63 5f 69 74 75 5f 70 70 6c 5f 70 72 00]
Query Entities 0x02 (State/Event Table), 0x03 (Protocol), and 0x07 (Extended State/Event Table) would return similar results.