Did you know ... | Search Documentation: |
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