You are here: CSP API Reference > 1 EXS & SwitchKit API Messages > PPL Audit Query 0x00DD

PPL Audit Query 0x00DD

Chapter 0 Query API Messages

SwitchKit Name

PPLAuditQuery

Type

EXS API and SwitchKit API message

Description

PPL Audit Query 0x00DD

The host uses this message to request an audit for individual PPL components or entities. The CSP maintains two logs: the PPL state transition log and the PPL error log. Therefore, the host can use this message for two types of audits:

1. PPL State Transition audit
This audit retrieves information on a per-instantiated PPL component basis.

2. PPL Error audit
This audit retrieves information on a per-card basis.

The response to this message is the PPL audit. Its contents, including the length of the audit entry, varies per PPL component.

PPL component audits consist of one or more audit blocks, which in turn are made up of one or more audit entries. Each one of these messages queries one audit block. In order to audit a PPL component completely, the host must send several of these messages.

When there are no audit entries remaining, the response status to the PPL Audit Query message will indicate 0x00D7 (End of PPL Audit Data).

Prior to using this message, you must enable auditing using the PPL Audit Configure message.

Sent by

Host

SwitchKit Code

C Structure

typedef struct {

UBYTE AddrInfo[30];

unsigned short ComponentID;

UBYTE AuditType;

UBYTE AuditBlock;

} XL_PPLAuditQuery;

C Structure Response

typedef struct {

unsigned short Status;

UBYTE AddrInfo[30];

unsigned short ComponentID;

UBYTE AuditType;

UBYTE AuditBlock;

UBYTE AuditEntryLength;

UBYTE NumberAuditEntries;

UBYTE AuditEntries[215];

} XL_PPLAuditQueryAck;

C++ Class

class XLC_PPLAuditQuery : public XLC_OutboundMessage {

public:

const UBYTE *getAddrInfo() const;

UBYTE *getAddrInfo();

void setAddrInfo(UBYTE *x);

XBYTE getSpan() const;

void setSpan(XBYTE x);

UBYTE getChannel() const;

void setChannel(UBYTE x);

UBYTE getSlot() const;

void setSlot(UBYTE x);

XBYTE getV5ID() const;

void setV5ID(XBYTE x);

unsigned short getComponentID() const;

void setComponentID(unsigned short x);

UBYTE getAuditType() const;

void setAuditType(UBYTE x);

UBYTE getAuditBlock() const;

void setAuditBlock(UBYTE x);

};

C++ Class Response

class XLC_PPLAuditQueryAck : public XLC_AcknowledgeMessage {

public:

unsigned short getStatus() const;

void setStatus(unsigned short x);

const UBYTE *getAddrInfo() const;

UBYTE *getAddrInfo();

void setAddrInfo(UBYTE *x);

XBYTE getSpan() const;

void setSpan(XBYTE x);

UBYTE getChannel() const;

void setChannel(UBYTE x);

UBYTE getSlot() const;

void setSlot(UBYTE x);

XBYTE getV5ID() const;

void setV5ID(XBYTE x);

unsigned short getComponentID() const;

void setComponentID(unsigned short x);

UBYTE getAuditType() const;

void setAuditType(UBYTE x);

UBYTE getAuditBlock() const;

void setAuditBlock(UBYTE x);

UBYTE getAuditEntryLength() const;

void setAuditEntryLength(UBYTE x);

UBYTE getNumberAuditEntries() const;

void setNumberAuditEntries(UBYTE x);

const UBYTE *getAuditEntries() const;

UBYTE *getAuditEntries();

void setAuditEntries(UBYTE *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 (0xNNNN)
3, 4 | Message Type (0x00DD) | 3, 4 | Message Type (0x00DD)
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
: | : | 10 | AIB (starting with byte 0)
: | PPL Component ID MSB, LSB | : | PPL Component ID (MSB, LSB)
: | Audit Type | : | Audit Type
: | Audit Block Number | : | Audit Block Number
: | Checksum | : | Number of Audit Entries in this response.
|  | : | Audit Entry Length
|  | : | Audit Entry 0: Data[0]
|  | : | :
|  | : | Audit Entry 1: Data[0]
|  | : | :
|  | : | Audit Entry (n-1): Data[0]
|  | : | :
|  | N+3 | Checksum

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 (0x00DD) | 3, 4 | Message Type (0x00DD)
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 0x01 - Slot | 8, 9 | Status MSB, LSB
Number of AEs to follow
AE 0x0D Channel
: | PPL Component ID MSB, LSB See PPL Component IDs in the API Reference.
: | Audit Type 0x00 PPL State Transition Audit 0x01 PPL Error Audit 0x02 Audit Configuration | 10 | AIB 0x0D Channel The response can contain the AIB in two areas: -Immediately following the Status field: The address type that immediately follows the Status field is the same as the address type that the host included in the message. -Within each audit entry: The response may use any address type within each audit entry.
: | Audit Block Number The audit block you are querying. Begin an audit by specifying Audit Block Number 0 to retrieve the entire log. Repeatedly send this message, incrementing the block number, until the response status is 0x00D7 (PPL End of Auditing Data). | : | PPL Component ID (MSB, LSB)
: | Checksum | : | Audit Type 0x00 PPL State Transition Audit 0x01 PPL Error Audit 0x02 Audit Configuration The 0x02 audit type is a bit mask that enables audit configuration settings. The bit values are 0=Disabled, 1=Enabled. (To enable a feature, set the bit to 1). Bit 0 PPL Auditing Log 1 PPL Error Alarm 2 PPL Individual Log 3 PPL Entity Audit Log* 4 PPL Entity Error Alarm* * Bits 3 and 4 are invalid in Slot AIB.
: | Audit Block Number
| Response continued below.
: | Number of Audit Entries in this response. You can calculate the number of data bytes that follow this field by multiplying the values of this field and the Audit Entry Length field.(n)
: | Audit Entry Length The number of bytes in each audit entry.
: | Audit Entry 0: Data[0] The audit data varies by audit type and PPL Component. The data is returned for each audit entry in the block. See the text below this table for specific data listed by Audit Type/Entry. If there is no audit information for an entry, all data field values are 0x00. If the value of the Audit Type field is 0x00, valid entries for the Data fields are as follows: E1/T1 PPL Components Data[0] PPL Protocol ID Data[1] State Status Data[2, 3] PPL Event (MSB, LSB) Data[4] Initial State Data[5] Next State Data[6, 7] Timestamp (MSB, LSB) Data[8, 9] PPL Error Status (MSB, LSB) ISDN/DASS 2 PPL Components Data[0] Subrate Data[1, 2] Call Reference (MSB, LSB) Data[3] SAPI Data[4] CES Data[5] PPL Protocol ID Data[6] State Status Data[7, 8] PPL Event (MSB, LSB) Data[9] Initial State Data[10] Next State Data[11, 12] Timestamp (MSB, LSB) Data[13, 14] PPL Error Status (MSB, LSB)
| SS7 Components Data[0] PPL Protocol ID Data[1] State Status Data[2, 3] PPL Event (MSB, LSB) Data[4] Initial State (If State value is greater than 255, this is truncated to 0xFF) Data[6] Next State (If State value is greater than 255, this is truncated to 0xFF) Data[6, 7] Timestamp (MSB, LSB) Data[8, 9] PPL Error Status (MSB, LSB)
| For error audits, AIBs are retrieved for each audit entry. If the value of the Audit Type field is 0x01, valid entries for the Data fields are as follows: E1/T1 PPL Components Data[0] AIB : : Data[:] PPL Protocol ID Data[:] State Status Data[:] PPL Event (MSB, LSB) Data[:] Initial State Data[:] Next State Data[:] Timestamp (MSB, LSB) Data[:] PPL Error Status (MSB, LSB) ISDN/DASS 2 PPL Components Data[0] AIB : : Data[:] Reserved Data[:] Call Reference (MSB, LSB) Data[:] Reserved Data[:] Reserved Data[:] PPL Protocol ID Data[:] State Status Data[:] PPL Event (MSB, LSB) Data[:] Initial State Data[:] Next State Data[:] Timestamp (MSB, LSB) Data[:] PPL Error Status (MSB, LSB)
| SS7 Components The data begins with an AIB: Data[0] AIB : : Data[:] PPL Protocol ID Data[:] State Status Data[:] PPL Event (MSB, LSB) Data[:] Initial State Data[:] Next State Data[:] Timestamp (MSB, LSB) Data[:] PPL Error Status (MSB, LSB)
| If the value of the Audit Type field is 0x02, valid entries for the Data fields are as follows: E1/T1 PPL Components Data[0] PPL Protocol ID Data[1] State Status Data[2, 3] PPL Event (MSB, LSB) Data[4] Initial State (If State value is greater than 255, this is truncated to 0xFF) Data[5] Next State (If State value is greater than 255, this is truncated to 0xFF) Data[6, 7] Timestamp (MSB, LSB) Data[8, 9] PPL Error Status (MSB, LSB) Data[10, 11] Extended Initial State (MSB, LSB) Data[12, 13] Extended Next State (MSB, LSB) ISDN/DASS 2 PPL Components Data[0] Subrate Data[1, 2] Call Reference (MSB, LSB) Data[3] SAPI Data[4] CES Data[5] PPL Protocol ID Data[6] State Status Data[7, 8] PPL Event (MSB, LSB) Data[9] Initial State (If State value is greater than 255, this is truncated to 0xFF) Data[10] Next State (If State value is greater than 255, this is truncated to 0xFF) Data[11, 12] Timestamp (MSB, LSB) Data[13, 14] PPL Error Status (MSB, LSB) Data[15, 16] Extended Initial State (MSB, LSB) Data[17, 18] Extended Next State (MSB, LSB) SS7 Components Data[0] PPL Protocol ID Data[1] State Status Data[2, 3] PPL Event (MSB, LSB) Data[4] Initial State (If State value is greater than 255, this is truncated to 0xFF) Data[6] Next State (If State value is greater than 255, this is truncated to 0xFF) Data[6, 7] Timestamp (MSB, LSB) Data[8, 9] PPL Error Status (MSB, LSB) Data[10, 11] Extended Initial State (MSB, LSB) Data[12, 13] Extended Next State (MSB, LSB)
| If the value of the Audit Type field is 0x03, valid entries for the Data fields are as follows: E1/T1 PPL Components Data[0] AIB : : Data[:] PPL Protocol ID Data[:] State Status Data[:] PPL Event (MSB, LSB) Data[:] Initial State (If State value is greater than 255, this is truncated to 0xFF) Data[:] Next State (If State value is greater than 255, this is truncated to 0xFF) Data[:] Timestamp (MSB, LSB) Data[:] PPL Error Status (MSB, LSB) Data[:] Extended Initial State (MSB, LSB) Data[:] Extended Next State (MSB, LSB) ISDN/DASS 2 PPL Components Data[0] AIB : : Data[:] Reserved Data[:] Call Reference (MSB, LSB) Data[:] Reserved Data[:] Reserved Data[:] PPL Protocol ID Data[:] State Status Data[:] PPL Event (MSB, LSB) Data[:] Initial State (If State value is greater than 255, this is truncated to 0xFF) Data[:] Next State (If State value is greater than 255, this is truncated to 0xFF) Data[:] Timestamp (MSB, LSB) Data[:] PPL Error Status (MSB, LSB) Data[:] Extended Initial State (MSB, LSB) Data[:] Extended Next State (MSB, LSB) SS7 Components The data begins with an AIB: Data[0] AIB : : Data[:] PPL Protocol ID Data[:] State Status Data[:] PPL Event (MSB, LSB) Data[:] Initial State (If State value is greater than 255, this is truncated to 0xFF) Data[:] Next State (If State value is greater than 255, this is truncated to 0xFF) Data[:] Timestamp (MSB, LSB) Data[:] PPL Error Status (MSB, LSB) Data[:] Extended Initial State (MSB, LSB) Data[:] Extended Next State (MSB, LSB)
| VDAC-ONE and IP Network Interface Series 2 Components Data[0] AIB : : Data[:] PPL Protocol ID Data[:] Blocked Data[:] PPL Event (MSB, LSB) Data[:] Initial State Data[:] Next State Data[:] Timestamp (MSB, LSB) Data[:] PPL Error Status (MSB, LSB) Data[:] Extended Initial State (MSB, LSB) Data[:] Extended Next State (MSB, LSB)
: | Audit Entry 1: Data[0]
: | :
: | Checksum

State Status

This byte indicates whether or not a blocking atomic function has been invoked by the state machine. A blocking atomic function is used for allocation of any off-board service resource required by the PPL.

Once the result of the resource request is received, the channel unblocks and resumes the remainder of the primitive. Blocking is performed on a channel basis without affecting other channels.

0x00 Normal

0xFF Blocking

Timestamp

The timestamp is an incrementing 10 ms timer representing the relative time between PPL events. After reaching the value of OxFFFF, the timer resets to zero.

PPL Error Status

Valid entries for this word-length field are as follows:

0x0000 No Error

0xF448 Invalid event for next state

0xF447 Invalid event for initial state

0xF446 Blocked message

0xF445 Blocked event

0xF444 Invalid event for blocked state

0xF443 Internal error (wrong task ID)

0xF442 Internal error (invalid header)

0xF441 Internal error (invalid header)

0xF440 Invalid event

0xF43E Timer is disabled

0xF43D Timer expired out of sequence

0xF43C Event not processed

0xF43B Internal error (invalid message)

0xF43A Cannot create new context

0xF439 Cannot enter new context

0xF438 Entering new context

0xF437 Leaving new context

0xF436 Invalid context

0xF435 No state/event list

0xF434 State machine suspended

0xF433 Timer expired while in blocked state

0xF432 Invalid response to blocked state

0xF431 Not waiting on internal event

0xF430 Initiated Channel purge

0xF42F Maximum iterations of state machine exceeded

0xF42E Null primitive

0xF42D Context is inconsistent

0xF42C Maximum nesting level exceeded

0xF42B Initiated state machine reset

0xF42A Maximum config byte offset exceeded

0xF429 Maximum number of GPRs exceeded

0xF420 Block Invalid Events

0xF41F Invalid Event Handler Activated

Example Message

This example shows a PPL Audit Query message that is being used to query a PPL State Transition audit log on logical span 0/channel 0, ISDN component #5. The message from the host to the CSP is as follows:

Header:

fe [00 16] [00 dd] 00 00 ff

AIB:

00 01 0D 03 00 00 00

Info:

[00 05] 00 00

MESSAGE
Byte | Field Description | Value and Indication
0 | Frame | 0xFE
1 | Length (MSB, LSB) | 0x0016 (22)
2
3 | Message Type (MSB, LSB) | 0x00DD (PPL Audit Query)
4
5 | Reserved | 0x00
6 | Sequence # | 0x00
7 | Logical Node ID | 0xFF
8 | AIB | 0x00 (Single Entity)
9 | Number of Address Elements | 0x01
10 | Address Type | 0x0D (Channel)
11 | Data Length | 0x03
12 | Logical Span (MSB, LSB) | 0x0000 (Span 0)
13
14 | Channel | 0x00 (Channel 0)
15 | PPL Component ID (MSB, LSB) | 0x0005 (ISDN L3P Call Reference)
16
17 | Audit Type | 0x00 (PPL State Transition Audit)
18 | Audit Block | 0x00 (Block 0)
19 | Checksum | 0xCS (does not appear in trace)

The trace of the response shows that 14 bytes of data are returned for each of nine audits on the specified channel/PPL component. The response, containing the log information, is as follows:

Header:

fe [00 92] [00 dd] 00 15 ff [00 10]

AIB:

00 01 0d 03 00 00 00

Info:

[00 05] 00 00 0f 09

Audit Entry 0:

00 00 00 00 0b 00 00 56 00 16 1d cd 00 00

Audit Entry 1:

00 00 00 00 0b 00 00 c9 16 06 1d cd 00 00

Audit Entry 2:

00 00 00 01 0b 00 00 67 06 1a 1e 96 00 00

Audit Entry 3:

00 00 00 01 0b 00 00 c8 1a 0b 1e 96 00 00

Audit Entry 4:

00 00 00 01 0b 00 00 c8 0b 06 1e 96 00 00

Audit Entry 5:

00 00 00 01 0b 00 00 69 06 19 1e 9e 00 00

Audit Entry 6:

00 00 00 01 0b 00 00 c8 19 0c 1e 9e 00 00

Audit Entry 7:

00 00 00 01 0b 00 00 c9 0c 04 1e 9e 00 00

Audit Entry 8:

00 00 00 01 0b 00 00 54 04 05 26 65 00 00

X->H

Header:

ff b1 dd 15 10

AIB:

00 01 02 02 00 00

Info:

00 05 00 00 12 09

Audit Entry 0:

00 00 00 00 00 00 00 0b 00 00 56 00 16 1d cd 00 00 ff

Audit Entry 1:

00 00 00 00 00 00 00 0b 00 00 c9 16 06 1d cd 00 00 ff

Audit Entry 2:

00 00 00 00 00 00 01 0b 00 00 67 06 1a 1e 96 00 00 ff

Audit Entry 3:

00 00 00 00 00 00 01 0b 00 00 c8 1a 0b 1e 96 00 00 ff

Audit Entry 4:

00 00 00 00 00 00 01 0b 00 00 c8 0b 06 1e 96 00 00 ff

Audit Entry 5:

00 00 00 00 00 00 01 0b 00 00 69 06 19 1e 9e 00 00 ff

Audit Entry 6:

00 00 00 00 00 00 01 0b 00 00 c8 19 0c 1e 9e 00 00 ff

Audit Entry 7:

00 00 00 00 00 00 01 0b 00 00 c9 0c 04 1e 9e 00 00 ff

Audit Entry 8:

00 00 00 00 00 00 01 0b 00 00 54 04 05 26 65 00 00 ff

The following shows the response in the format of the API message table. The data for the first audit entry only is detailed.

RESPONSE
Byte | Field Description | Value and Indication
0 | Frame | 0xFE
1, 2 | Length (MSB, LSB) | 0x0092
3, 4 | Message Type (MSB, LSB) | 0x00DD (PPL Audit Query)
5 | Reserved | 0x00
6 | Sequence # | 0x15
7 | Logical Node ID | 0xFF
8, 9 | Status (MSB, LSB) | 0x0010 (Positive ACK)
10 | AIB | 0x00 (Single Entity)
11 | # of Address Elements | 0x01
12 | Address Type | 0x0D (Channel)
13 | Data Length | 0x03
14, 15 | Logical Span (MSB, LSB) | 0x0000 (Span 0)
16 | Channel | 0x00 (Channel 0)
17, 18 | PPL Component ID (MSB, LSB) | 0x0005 (ISDN L3P Call Reference)
19 | Audit Type | 0x00 (PPL State Transition Audit)
20 | Audit Block Number | 0x00 (Block 0)
21 | Audit Entry Length | 0x0F (15)
22 | Number Of Audit Entries | 0x09 (9)
23 | Audit Entry 0 Data[0] Reserved | 0x00
24 | Data[1] Reserved | 0x00
25, 26 | Data[2,3] Call Reference (MSB, LSB) | 0x0000
27 | Data[4] PPL Protocol ID | 0x0B (Protocol ID 11)
28 | Data[5] State Status | 0x00 (Normal)
29, 30 | Data[6,7] PPL Event (MSB, LSB) | 0x0056
31 | Data[8] Initial State | 0x00
32 | Data[9] Next State | 0x16
33, 34 | Data[10,11] Timestamp (MSB, LSB) | 0x1DCD
35, 36 | Data[12,13] Error Status (MSB, LSB) | 0x0000
37-50 | Audit Entry 1: Data[0-13] | see trace for data
51-64 | Audit Entry 2: Data[0-13] | see trace for data
65-78 | Audit Entry 3: Data[0-13] | see trace for data
79-92 | Audit Entry 4: Data[0-13] | see trace for data
93-106 | Audit Entry 5: Data[0-13] | see trace for data
107-120 | Audit Entry 6: Data[0-13] | see trace for data
121-134 | Audit Entry 7: Data[0-13] | see trace for data
135-148 | Audit Entry 8: Data[0-13] | see trace for data
149 | Checksum | 0xCS (not shown in trace)

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.
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.
See Address Information Block.
Most Significant Bit
Least Significant Bit
A programmable software component that uses PPL state machines that can be modified with the PPL Tool.
A digital communications link - voice, data, and video at a 2.048 Mbps rate; 30B/2D or 31B/1D (ISDN); non-North American version of T1.
Digital communications link - voice, data, and video at a 1.544 Mbps rate (24 64 Kbps channels)
A condition that, when met, drives a state machine from one state to another. A condition that drives a Component out of its current state by invoking an associated primitive.
See Integrated Services Digital Network.
See Signaling System Number Seven.
Internet Protocol. Part of the TCP/IP family of protocols used to route messages and tracks the addresses of nodes.
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.
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.
Positive acknowledgment to a message