Global Data Server Logo Documentation Home  

GDS Query Exchange Control Bus


Agents are able to directly communicate between each other using the Control Bus. This is an internal system only visible to applications directly. This documentation is provided to assst advanced debug situations. Documentation on this page is very low level, and subject to change without warning.

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 can see all control commands, but control packets are typically addressed to individual agents or class of agents.

The control bus is not designed for high volume or large packets. It is primarily used for rare exceptions that don't require a full blown QE Request


Command Packet Structure

Field #NameDescription
100OpcodeOpcode/Command being sent
101ReqIdRequest Id string.
110TPidSingle Pid command is being sent too
120TClassClass of agents being targeted. Used when exact Pid is unknown. 1=Http 2=GdsDbMsAccess 3=Routing
121BucketTarget bucket for this command
122AgentSingle agent name command is being sent too. Not supported by all agents
150Data1Variable use parameter of type Integer. Exact purpose is left to each Opcode to define.
151String1Variable use parameter of type String. Exact purpose is left to each Opcode to define.
152CredIdCredential identifier (20 bytes)
153EnvironmentIdEnvironment Id
154FilePathComplete filename with full path
155DMEG.f12Data type identification. These are constants that define exact type of data (eg "locations" or "products") Essentially this is a primary key to metadata
156DbPathComplete Db path as might be used by database clients
157TableNameA table name for database backed information
158RmSystemA single RmSystem. Encoded as 4x32
159SourcePidRequesting Pid

Command List

Command #NameDescription
190CredentialsGetGet Credentials for id# passed in f152
200TimeTickA centrally generated tick pulse. Currently this is generated every 5 minutes. Clients are able to use this tick pulse for any purpose, but commonly it is used to schedule time based events rather than every client implementing their own time monitor
500OperatorRequest Operator assistance. Text of request in f151
501DumpRequest agents to write internal state to gds2dump.txt file.
2000PinbRequestRequest details of pinboards agents will respond too. Typically issued when a directory request is being made
3000PortAllocateRequest new available TCP/UDP port that can be assigned.
3002PortEnvStartStart a new Port/Environment
3003CreateDbCreate a blank database
3004SendSocketSend unexpected data to a socket
3005LinkStatusRequest Current link Status. LinkId is passed in f151
3006SendSocketCmdSend unexpected data to a socket. The data packet contains a list of commands, such as filenames, not the actual data
3007RmActiveRequest if an RmSystem is currently connected in GNAD mode
3008HttpFullRequest full HTTP request details
3009ConnectPortSecondary agent requesting port sharing details.
4000MeshConfigPlease list routing configuration
4001MeshFileReceivedA file has been received from mesh and is ready for post processing
5000DbidGetReturn Dbid for an environment
6000DbQuiesceRequest a database be taken offline for maintainance. Clients can return NAK if they do not wish to do this at this time. Database is specified by either EnvironmentId or DbPath
6001ReloadFilesInstructs agents to reload data from external files. Typically used when a reference file has changed and you want the processing agents to be aware of this now.
6002SelfExitRequests an Agent to exit.
6003DatabaseChangedInforms Gds that a database table has been altered outside of normal operation. This control message is not used by Gds internally but should be used by external applications after tables have been altered. The TableName parameter is required and cannot contain wildcards. See below for more details.
6004MetaDataChangedInforms Gds that a database table structure has been altered

Reply Packet Structure

Field #NameDescription
101ReqIdRequest Id being responded too
501OperatorReplyOperator reply code
2000Date/TimeLast Receive Date/Time Response to Opcode=3005
3001PortAvailable port number. Response to Opcode=3000
3002Inbound AddressIp address for a link. ie, what ip address did it connect too. Response to Opcode=3005
3003Inbound PortIp port for a link. ie, what ip port did it connect too. Response to Opcode=3005
3004LinkIdNetwork LinkId
3005UserAgentHttp UserAgent
3006PortInfoDetails of shared port
5001DbidDatabase Dbid

Operator Requests

When a program or agent detects some sorts of problems it is able to raise an operator request rather than aborting processing immediately. For example, a program that expects a certain file to exist can raise an operator request to place the file as expected. Operator requests are expected to be handled by a human operator.

Operators can correct the action and continue the program or abort the program.

Examples

Flushing caches

As Gds makes extensive use of caching, external applications that directly alter the database need to advise Gds that caches may contain stale data.

GlobalData /control databasechanged /tablename=customers /tablename=products

Gds uses variable length cache timers depending on the data and request. "Total revenue today" data (tables sales, salelines, payments etc) is cached with very small windows, around 30 seconds and invalidates on new sale arrival.

"Total revenue last year" is cached with much a longer window, potentially hours or days. If you change last years sales data externally then you will need to invalidate the caches as shown

Simply restarting Gds to flush caches is not guaranteed to work reliably. Some cache files are reused over a restart and some caching can be held in processes that are not affected by a simple Gds restart. However, in general the use of the databasechanged command is not always required. Gds understands that some tables will be externally changed and does not use long cache timeouts for this sort of data

Changing Tables

If you change the physical structure of a database table, such as adding a new field then you can advise Gds of this

GlobalData /control metadatachanged /tablename=mynewtable

On restart of Gds, metadata is always checked, so this command is only required if you want Gds to detect a field change without restarting