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 # | Name | Description |
| 100 | Opcode | Opcode/Command being sent |
| 101 | ReqId | Request Id string. |
| 110 | TPid | Single Pid command is being sent too |
| 120 | TClass | Class of agents being targeted. Used when exact Pid is unknown. 1=Http 2=GdsDbMsAccess 3=Routing |
| 121 | Bucket | Target bucket for this command |
| 122 | Agent | Single agent name command is being sent too. Not supported by all agents |
| 150 | Data1 | Variable use parameter of type Integer. Exact purpose is left to each Opcode to define. |
| 151 | String1 | Variable use parameter of type String. Exact purpose is left to each Opcode to define. |
| 152 | CredId | Credential identifier (20 bytes) |
| 153 | EnvironmentId | Environment Id |
| 154 | FilePath | Complete filename with full path |
| 155 | DMEG.f12 | Data type identification. These are constants that define exact type of data (eg "locations" or "products") Essentially this is a primary key to metadata |
| 156 | DbPath | Complete Db path as might be used by database clients |
| 157 | TableName | A table name for database backed information |
| 158 | RmSystem | A single RmSystem. Encoded as 4x32 |
| 159 | SourcePid | Requesting Pid |
Command List
| Command # | Name | Description |
| 190 | CredentialsGet | Get Credentials for id# passed in f152 |
| 200 | TimeTick | A 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 |
| 500 | Operator | Request Operator assistance. Text of request in f151 |
| 501 | Dump | Request agents to write internal state to gds2dump.txt file. |
| 2000 | PinbRequest | Request details of pinboards agents will respond too. Typically issued when a directory request is being made |
| 3000 | PortAllocate | Request new available TCP/UDP port that can be assigned. |
| 3002 | PortEnvStart | Start a new Port/Environment |
| 3003 | CreateDb | Create a blank database |
| 3004 | SendSocket | Send unexpected data to a socket |
| 3005 | LinkStatus | Request Current link Status. LinkId is passed in f151 |
| 3006 | SendSocketCmd | Send unexpected data to a socket. The data packet contains a list of commands, such as filenames, not the actual data |
| 3007 | RmActive | Request if an RmSystem is currently connected in GNAD mode |
| 3008 | HttpFull | Request full HTTP request details |
| 3009 | ConnectPort | Secondary agent requesting port sharing details. |
| 4000 | MeshConfig | Please list routing configuration |
| 4001 | MeshFileReceived | A file has been received from mesh and is ready for post processing |
| 5000 | DbidGet | Return Dbid for an environment |
| 6000 | DbQuiesce | Request 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 |
| 6001 | ReloadFiles | Instructs 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. |
| 6002 | SelfExit | Requests an Agent to exit. |
| 6003 | DatabaseChanged | Informs 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. |
| 6004 | MetaDataChanged | Informs Gds that a database table structure has been altered |
Reply Packet Structure
| Field # | Name | Description |
| 101 | ReqId | Request Id being responded too |
| 501 | OperatorReply | Operator reply code |
| 2000 | Date/Time | Last Receive Date/Time Response to Opcode=3005 |
| 3001 | Port | Available port number. Response to Opcode=3000 |
| 3002 | Inbound Address | Ip address for a link. ie, what ip address did it connect too. Response to Opcode=3005 |
| 3003 | Inbound Port | Ip port for a link. ie, what ip port did it connect too. Response to Opcode=3005 |
| 3004 | LinkId | Network LinkId |
| 3005 | UserAgent | Http UserAgent |
| 3006 | PortInfo | Details of shared port |
| 5001 | Dbid | Database 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