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

The host uses this message to request an audit for individual PPL components or entities. The Excel platform 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 Excel platform 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)