Quick Links: Site Home | Documentation

GDS Query Exchange Debugger

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.

Bus layout

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 #NameDescription
100OpcodeCommand requested. Required
101ExcodeExecutor 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
102RequestKeyOptional unique identifier that will be replicated to the reply
110PidTarget Process Id. Zero if not selecting a specific process id
112TidTarget Thread Id

Optional Arguments

99Unused parameter that can be used as cache breaking value when QeDebug is sent over cachable protocols such as HTTP.
103EnvironmentIdEnvironment id. Used internally, do not pass directly
120MaxWaitMaximum time to wait. Approx milliseconds not exact.
121MaxReplyMaximum number of replies to wait for. When this many are received the call returns.
600PathDirectory Path
601FlagsOperation control flags for the individual command
602ControlNumberGeneral purpose number argument. The exact purpose is up to each command to decide.
603TableNameName of a database table
604SqlSimple SQL statement
605SearchGeneral purpose string for search purposes. Individual packets can determine exact meaning
606ThreadSelectThread 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.
607FieldNameName of a database field
608TableNameBName of a database table. Used when multiple tables are required as arguments
609FieldNameBName of a database field. Used when multiple fields are required as arguments
610ModuleSelectName of a single module that should respond

Example (in XML representation)

	<f100>301</f100>		-- Send settings

Command List

Command #NameDescription
1Hello1Request a hello message with reply posted to debugger
2Hello2Request a hello message with reply posted to the activity ring
200CurStatus 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.
201DetailedStatus Request a detailed status packet.
202LiveTrace 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.
300GetPrivateLogRequest 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
301GetSettingsRequest 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.
302SetSettingsSet a setting value (see 301)
18,100PhysHardRequest physical hardware details. (fdl911)
18,200DiskFilesRequest disk and files overview. (fdl911)
18,300NetworkOverviewOverview information about the network capabilities. (fdl911)
21,000DiskFirstFirst level disk checks. (fdl911)
21,001DiskFilesInformation about files in a single folder (fdl911)
21,100PrinterOverviewOverview of printers and print queues. (fdl911)
22,000PosFilesKey POS files request. Crash information, error logs etc. (fdl911)
22,001PosErrorStateCurrent Pos error indicators. (fdl911)
25,000PosIStateFieldpine PosGreen only. Return internal dynamic state summary. Details
25,001FlowDumpFieldpine PosGreen only. Returns details of internal flow. Details
25,007TimersFieldpine PosGreen only. Current internal timers recording the duration of parts of processing Details
50,000TUSHRequest a TUSH block
50,001PosCmdProcess PosCommands. This command is only used by PosGreen.
70,000IgnoreListReturn the current QueryExchange Ignore list
82,010ForceCrashRegister 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
121003DbStorage_TableSummary Requests fpos.dll to return a summarised packet about the rows inside a single table Details
121006DbcDao2000_Overview Requests dbcdao2000.dll, if in use, to respond with overview details about the database(s) connected and the operating environment. Details
121007DbcDao2000_Metadata Requests dbcdao2000.dll, if in use, to respond with complete metadata information for the current database. Details
121008DbcDao2000_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,200ThreadList Return details about all threads in the target process.
140,201ProcessMemoryDetails about current process memory.
140,202ProcessModulesInformation on modules loaded into process memory.
140,203PerformanceCountersCurrent 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,006Locale 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,001DiskSMART Retrieve S.M.A.R.T. counters from disk drives Details
154,002DiskSampler Performs structured read IO to a disk and measures the response times. Details
155,000 - 155,999 Reserved for commands relating to networks
155,001NetworkOverview 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,000EftposENZStatus Return general status of ENZ eftpos
157,001EftposENZVersionsReturn extended ENZ version information
210,000 - 210,999 Reserved for mesh networking specific commands
210,000MeshOverview Summary information about active configuration
210,001MeshTest Internal testing functions. Reserved for internal debugging. Not recommended to call.
210,002MeshDiscovery Information about detected network topology and partners we can communicate with
210,031MeshApiStats 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,001AddressOverview General details from the Address Agent

Reply Packet Structure

Field #NameDescription
100OpcodeOpcode being responded too
101ExcodeExcode being responded too
102RequestKeyOptional unique identifier copied from the command packet
110PidReplying Process Id
111NameCommon Agent Name
112TidReplying Thread Id
113KeySession identification key.
114SampleTimeDate/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.
115SampleTimeUTCDate/Time this sample was taken. Same information as f114 (SampleTime), but using UTC
120StatusA status code indicating overall response. 0=Data does not exist
121LengthLength of data being returned. This is the data, not this response packets length
122Length2Length of information. Opcode specific meaning.
123CommentHuman readable comment about the response. Might be used to convey additional information, but is not designed to be parsed and used by systems.
124RowCountNumber of rows. Exact meaning of 'row' depends on function called
501DateTimeA date/time value, typically build date and time
510Data1Opcode specific response data. Content meaning varies depending on Opcode
600PLevelVersion in PLevel PLevel is a simple ascending number increased each build
601VersionFull Version
602Unique identifier (licid, uid etc)
603HttpPortLocal Port for HTTP server, if present
700ImageDataBinary 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.
701ImageDataTypeShort code indicating the type of data returned in 700. 0=Unknown
1603TableNameName 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 #NameDescription
110NameShort Friendly name of setting. The same name can be used by different agents for different purposes
111CurrentValueCurrent value of the setting
112EnvironmentContains an environment number if this setting is specific to a single environment.
113ValueTypeCoded value indicating what sort of values are acceptable. ValueType 1 = 0/1 for no/yes respectively
Following fields are not normally used by QeDebug directly, but other APIs that use the SETT packet
150DescriptionA description describing the setting.
151ScopeIs 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).
152PriorityHow "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
153TitleA short description describing the setting.
154ErrorHow important errors in this setting are considered to be.