Each agent connected to Query Exchange can optionally include the QeDebug facility which allows a central debugger to communicate to agents while they are processing. This document outlines the protocol used by the debugger, not directly how to use QeDebug.
Details on how to write support tools or enterprise monitoring using Debug commands can be found in How to Use QeDebug Commands for enterprise monitoring
The protocol is a packet based system with asyncronous command and reply packets. Each command packet is placed on a shared communication bus and agents read this bus. All agents see all debug commands, but command packets are typically addressed to individual agents so single agent debugging is possible.
The command and reply communication channels are typically implemented as in memory ring buffers, so agents and debugger need to be reasonably responsive. However, the communication bus can vary from shared memory to TCP, UDP or other methods, so packet transmission is not always physically to all nodes.
The Fieldpine 911 automated online support uses the debug protocol with some additional request/response types suitable for generic problem investigation
Technical. Debug Protocol can also be sent over channel 5 on GNAD links. This permits remote programs to communicate debug control information specifically. The protocol described here is also known as TUBS protocol 4.
The QeDebug protocol includes information about internal operation and can be highly dependant on version and specific operating conditions. Reply packet contents may not be fully documented as the information is considered too technical, sensitive, not mainstream or experimental. Not all fields will be documented. In general, fields are only documented if they are of use without intricate knowledge of the source code. Most users do not care about the size of an array or information controlling algorithms. Anything that could be useful to support will generally be documented. The rule for developers is to document, unless there is reason not too.
Command Packet Structure
| Field # | Name | Description |
| 100 | Opcode | Command requested. Required |
| 101 | Excode | Executor group for Opcode. If not supplied the default executor is invoked. Each Opcode is passed to the
relevant Excode handler, which means that the same opcode number can have different purposes for different Excode handlers. The opcodes listed
on this page are for Excode=0 (default). Other codes are: 21 External Command, 32 Mini C, 43 Advisor Test |
| 102 | RequestKey | Optional unique identifier that will be replicated to the reply |
| 110 | Pid | Target Process Id. Zero if not selecting a specific process id |
| 112 | Tid | Target Thread Id |
Optional Arguments | ||
| 99 | Unused parameter that can be used as cache breaking value when QeDebug is sent over cachable protocols such as HTTP. | |
| 103 | EnvironmentId | Environment id. Used internally, do not pass directly |
| 120 | MaxWait | Maximum time to wait. Approx milliseconds not exact. |
| 121 | MaxReply | Maximum number of replies to wait for. When this many are received the call returns. |
| 600 | Path | Directory Path |
| 601 | Flags | Operation control flags for the individual command |
| 602 | ControlNumber | General purpose number argument. The exact purpose is up to each command to decide. |
| 603 | TableName | Name of a database table |
| 604 | Sql | Simple SQL statement |
| 605 | Search | General purpose string for search purposes. Individual packets can determine exact meaning |
| 606 | ThreadSelect | Thread selector. Used to select the reporting of specific thread by another thread. Typically this is used on calls that allow thread A to peek into thread B and return information. Rarely used. |
| 607 | FieldName | Name of a database field |
| 608 | TableNameB | Name of a database table. Used when multiple tables are required as arguments |
| 609 | FieldNameB | Name of a database field. Used when multiple fields are required as arguments |
| 610 | ModuleSelect | Name of a single module that should respond |
Example (in XML representation)
<DATI> <f100>301</f100> -- Send settings </DATI>
Command List
| Command # | Name | Description |
| 1 | Hello1 | Request a hello message with reply posted to debugger |
| 2 | Hello2 | Request a hello message with reply posted to the activity ring |
| 200 | CurStatus | Request a complete current status packet detailing each thread and critical internal state. This packet is expected to summarise internal activity. It is expected to be reasonably large perhaps around 5K per program. |
| 201 | DetailedStatus | Request a detailed status packet. |
| 202 | LiveTrace | Contains a live trace message. This packet type cannot be requested, the tested system constantly sends these messages when capturing of live trace is enabled. |
| 300 | GetPrivateLog | Request details of private internal logging buffers. Typically used by applications that maintain large in memory trace or history logs. For example, SQL agents typically keep details of last N queries performed against a database. Private logs may require the caller to have extended privilege to access this log |
| 301 | GetSettings | Request current settings in use or available to change. Settings are used to dynamically alter the runtime behaviour of an agent. Response consists of a number of settings blocks. F605 can be used to search for leading prefix. F601 controls search mode. 0 = Name starting with, 18 = Value like search, case insensitive. Responding agents are not required to implement search ability. |
| 302 | SetSettings | Set a setting value (see 301) |
| 18,100 | PhysHard | Request physical hardware details. (fdl911) |
| 18,200 | DiskFiles | Request disk and files overview. (fdl911) |
| 18,300 | NetworkOverview | Overview information about the network capabilities. (fdl911) |
| 21,000 | DiskFirst | First level disk checks. (fdl911) |
| 21,001 | DiskFiles | Information about files in a single folder (fdl911) |
| 21,100 | PrinterOverview | Overview of printers and print queues. (fdl911) |
| 22,000 | PosFiles | Key POS files request. Crash information, error logs etc. (fdl911) |
| 22,001 | PosErrorState | Current Pos error indicators. (fdl911) |
| 25,000 | PosIState | Fieldpine PosGreen only. Return internal dynamic state summary. Details |
| 25,001 | FlowDump | Fieldpine PosGreen only. Returns details of internal flow. Details |
| 25,007 | Timers | Fieldpine PosGreen only. Current internal timers recording the duration of parts of processing Details |
| 50,000 | TUSH | Request a TUSH block |
| 50,001 | PosCmd | Process PosCommands. This command is only used by PosGreen. |
| 70,000 | IgnoreList | Return the current QueryExchange Ignore list |
| 82,010 | ForceCrash | Register a force crash point. The agent will check to see if it should randomly crash when at this point. This command should never be used on production machines, it is implemented for stress testing purposes only. f1200 = Major, F1201=Minor, f1202=Rate |
| 121,000 - 121,999 | Range reserved for storage based commands, such as database checksum etc. More Details | |
| 121003 | DbStorage_TableSummary | Requests fpos.dll to return a summarised packet about the rows inside a single table Details |
| 121006 | DbcDao2000_Overview | Requests dbcdao2000.dll, if in use, to respond with overview details about the database(s) connected and the operating environment. Details |
| 121007 | DbcDao2000_Metadata | Requests dbcdao2000.dll, if in use, to respond with complete metadata information for the current database. Details |
| 121008 | DbcDao2000_Users | Requests dbcdao2000.dll, if in use, to respond with user lists for the database Details |
| 122,000 - 122,999 | Reserved for Fieldpine POS specific commands | |
| 122,000 | Return WM_xxxx counters. | |
| 122,001 | Details about Pos created thread types. Technical details about threads is 140,200 | |
| 122,500 | Inbound transactions sent to individual POS by local interfaces. | |
| 123,000 - 123,999 | Reserved for Fieldpine POS fpscreens.dll specific commands. Some of this range is undocumented as it may refer to customer specific information. | |
| 140,200 | ThreadList | Return details about all threads in the target process. |
| 140,201 | ProcessMemory | Details about current process memory. |
| 140,202 | ProcessModules | Information on modules loaded into process memory. |
| 140,203 | PerformanceCounters | Current values of performance counters |
| 150,000 - 150,999 | Reserved for printing and print queue related commands | |
| 150,000 | Print jobs information | |
| 150,001 | Printer driver dll files details | |
| 151,000 - 151,999 | Reserved for hardware specific commands | |
| 152,000 - 152,999 | Reserved for Operating system specific commands. more | |
| 152,002 | Current processes on system | |
| 152,003 | Report system ATOM table usage. | |
| 152,004 | Capture a current screenshot of the system | |
| 152,006 | Locale | Return all locale settings relating to date, time, currency, language. Some test values are also processed and returned to validate actual operation. |
| 154,000 - 154,999 | Reserved for commands relating to disks and files | |
| 154,001 | DiskSMART | Retrieve S.M.A.R.T. counters from disk drives Details |
| 154,002 | DiskSampler | Performs structured read IO to a disk and measures the response times. Details |
| 155,000 - 155,999 | Reserved for commands relating to networks | |
| 155,001 | NetworkOverview | Details about network adapters and top level information related to networks. Details |
| 156,001 | QeHardware performance test(s) | |
| 156,000 - 156,999 | Reserved for commands relating to performance and reliability testing | |
| 157,000 | EftposENZStatus | Return general status of ENZ eftpos |
| 157,001 | EftposENZVersions | Return extended ENZ version information |
| 210,000 - 210,999 | Reserved for mesh networking specific commands | |
| 210,000 | MeshOverview | Summary information about active configuration |
| 210,001 | MeshTest | Internal testing functions. Reserved for internal debugging. Not recommended to call. |
| 210,002 | MeshDiscovery | Information about detected network topology and partners we can communicate with |
| 210,031 | MeshApiStats | Details about RPC style calls made via mesh |
| 210,032 | Dynamically alter RPC rule table. Advanced, not for general use | |
| 300,000 - 300,999 | Commands for the address agent | |
| 300,001 | AddressOverview | General details from the Address Agent |
Reply Packet Structure
| Field # | Name | Description |
| 100 | Opcode | Opcode being responded too |
| 101 | Excode | Excode being responded too |
| 102 | RequestKey | Optional unique identifier copied from the command packet |
| 110 | Pid | Replying Process Id |
| 111 | Name | Common Agent Name |
| 112 | Tid | Replying Thread Id |
| 113 | Key | Session identification key. |
| 114 | SampleTime | Date/Time this sample was taken. Optional to return, but typically returned for tests that might be repeated in a single session and vary over time. This value is LocalTime. |
| 115 | SampleTimeUTC | Date/Time this sample was taken. Same information as f114 (SampleTime), but using UTC |
| 120 | Status | A status code indicating overall response. 0=Data does not exist |
| 121 | Length | Length of data being returned. This is the data, not this response packets length |
| 122 | Length2 | Length of information. Opcode specific meaning. |
| 123 | Comment | Human readable comment about the response. Might be used to convey additional information, but is not designed to be parsed and used by systems. |
| 124 | RowCount | Number of rows. Exact meaning of 'row' depends on function called |
| 501 | DateTime | A date/time value, typically build date and time |
| 510 | Data1 | Opcode specific response data. Content meaning varies depending on Opcode |
| 600 | PLevel | Version in PLevel PLevel is a simple ascending number increased each build |
| 601 | Version | Full Version |
| 602 | Unique identifier (licid, uid etc) | |
| 603 | HttpPort | Local Port for HTTP server, if present |
| 700 | ImageData | Binary Image data. This field contains binary data so callers that request commands that return binary data need to be able to correctly handle this data type. |
| 701 | ImageDataType | Short code indicating the type of data returned in 700. 0=Unknown |
| 1603 | TableName | Name of database table |
Settings Block Packet Structure - SETT
This packet is used when a setting is to be returned or set. Mainly used by commands GetSettings (301) and SetSettings (302).
| Field # | Name | Description |
| 110 | Name | Short Friendly name of setting. The same name can be used by different agents for different purposes |
| 111 | CurrentValue | Current value of the setting |
| 112 | Environment | Contains an environment number if this setting is specific to a single environment. |
| 113 | ValueType | Coded value indicating what sort of values are acceptable. ValueType 1 = 0/1 for no/yes respectively |
| 120 | ReadCount | |
| 121 | WriteCount | |
| 122 | Source | |
| Following fields are not normally used by QeDebug directly, but other APIs that use the SETT packet | ||
| 150 | Description | A description describing the setting. |
| 151 | Scope | Is the setting expected to be the same at different levels. 1=differs by lane, 2=differs by database, 3=differs by complete system (ie, all machines for a single retail environment are expected to have the same value). |
| 152 | Priority | How "user relevant" is the setting. A value from 1 to 10. A value of 1 indicates a setting that might be interesting to general users, while a value of 10 indicates an internal developer only setting This |
| 153 | Title | A short description describing the setting. |
| 154 | Error | How important errors in this setting are considered to be. |