1.6.1 Machine Query Interface Message Format

Every Machine Query Interface message is a single valid Prolog term. Those that run queries have an argument which represents the query as a single term. To run several goals at once use (goal1, goal2, ...) as the goal term.

The format of sent and received messages is identical (\n stands for the ASCII newline character which is a single byte):

<stringByteLength>.\n<stringBytes>.\n.

For example, to send hello as a message you would send this:

7.\nhello.\n

• <stringByteLength> is the number of bytes of the string to follow (including the .\n), in human readable numbers, such as 15 for a 15 byte string. It must be followed by .\n.
• <stringBytes> is the actual message string being sent, such as run(atom(a), -1).\n. It must always end with .\n. The character encoding used to decode and encode the string is UTF-8.

Important: The very first version of MQI (version 0.0) had a bug that required messages sent to (but not received from) MQI to use the count of Unicode code points (not bytes). This was fixed to properly require byte count in the next version, version 1.0.

To send a message to the MQI, send a message using the message format above to the localhost port or Unix Domain Socket that the MQI is listening on. For example, to run the synchronous goal atom(a), send the following message:

18.\nrun(atom(a), -1).\n<end of stream>

You will receive the response below on the receive stream of the same connection you sent on. Note that the answer is in JSON format. If a message takes longer than 2 seconds, there will be "heartbeat" characters (".") at the beginning of the response message, approximately 1 every 2 seconds. So, if the query takes 6 seconds for some reason, there will be three "." characters first:

...12\ntrue([[]]).\n