I have no official connection to basex, but I have played around with the server protocol with the idea of writing a Python driver for it that is more idiomatic Python and that better manages changes of state on the connection.
What I have discovered, at least as of BaseX 7.3, is the following:
A query can be executed multiple times, where "execute" means any of the result-producing commands: RESULTS, EXECUTE, FULL
A query *cannot* have any parameters rebound. In other words it's not possible to prepare a query, bind an external variable, execute the query, then bind another variable, execute again, and get another answer. Although no error will be reported when a var is rebound the results act as if it were not rebound.
So once a query is executed, you must treat the query as an immutable result. If you wish to issue the same query with a different bound value, you must create a new query with QUERY (producing a new query id).
Also, since there is no iterative partial execution of queries (like an SQL cursor, for example) and all results are returned at once, your question "how is the previous execution ended?" is not meaningful. The previous execution is ended when you receive results.
Closing a query deregisters it. It no longer has any existence, and any attempt to use it will return an error "Unknown Query ID".
Also note that query text does not seem to be evaluated when the query ID is created, so any syntax errors will not be caught until you directly (RESULTS, EXECUTE, FULL commands) or indirectly (OPTIONS command, maybe UPDATING as well?) execute the query.
I have written a very low level BaseX console in Python which I use to examine the exact semantics of the client-server protocol. Below is a log from one of those demonstrating many of the things I have said.
Lines that start with "?" are user-entered commands. A bare integer produces a byte of that value, and a double-quoted string produces a null-terminated utf8 string.
Lines starting with ">" are the bytes sent to the server, and "<" are the bytes received from the server.
Note that I have no idea what the "INFO" command is supposed to indicate!
? 0 "declare variable external $x; $x to $x+10"
> '\x00declare variable external $x; $x to $x+10\x00'
< '0\x00\x00'
? 6 0
> '\x06\x00\x00'
< '\x00\x01Unknown Query ID: \x00'
? 6 "0"
> '\x060\x00'
< '1\x00\x00'
? 3 "0" "x" "1" "xs:integer"
> '\x030\x00x\x001\x00xs:integer\x00'
< '\x00\x00'
? 6 "0"
> '\x060\x00'
< '\x00\x00'
? 7 "0"
> '\x070\x00'
< "\x00\x01Stopped at line 1, column 17:\n[XPST0003] Expecting '$', found 'e'.\x00"
? \2 "0"
> '\x020\x00'
< '\x00\x00'
? 0 "declare variable $x external'; $x to $x+10"
> "\x00declare variable $x external'; $x to $x+10\x00"
< '2\x00\x00'
? 2 "2"
> '\x022\x00'
< '\x00\x00'
? 0 "declare variable $x external; $x to $x+10"
> '\x00declare variable $x external; $x to $x+10\x00'
< '3\x00\x00'
? 6 "3"
> '\x063\x00'
< '\x00\x00'
? 7 "3"
> '\x073\x00'
< 'byte-order-mark=no,cdata-section-elements=,doctype-public=,doctype-system=,encoding=UTF-8,escape-uri-attributes=no,format=yes,include-content-type=no,indent=yes,indents=2,media-type=,method=xml,newline=\\n,normalization-form=NFC,omit-xml-declaration=yes,separator= ,standalone=omit,suppress-indentation=,tabulator=no,template=,undeclare-prefixes=no,use-character-maps=,version=,wrap-prefix=,wrap-uri=\x00\x00'
? 3 "3" "x" "0" "xs:integer"
> '\x033\x00x\x000\x00xs:integer\x00'
< '\x00\x00'
? 5 "3"
> '\x053\x00'
< '0 1 2 3 4 5 6 7 8 9 10\x00\x00'
? 4 "3"
> '\x043\x00'
< '40\x0041\x0042\x0043\x0044\x0045\x0046\x0047\x0048\x0049\x00410\x00\x00\x00'
? 31 "3"
> '\x1f3\x00'
< '40\x0041\x0042\x0043\x0044\x0045\x0046\x0047\x0048\x0049\x00410\x00\x00\x00'
? 3 "3" "x" "5" "xs:integer"
> '\x033\x00x\x005\x00xs:integer\x00'
< '\x00\x00'
? 4 "3"
> '\x043\x00'
< '40\x0041\x0042\x0043\x0044\x0045\x0046\x0047\x0048\x0049\x00410\x00\x00\x00'
? 5 "3"
> '\x053\x00'
< '0 1 2 3 4 5 6 7 8 9 10\x00\x00'
? 2 "3"
> '\x023\x00'
< '\x00\x00'
? 6 "3"
> '\x063\x00'
< '\x00\x01Unknown Query ID: 3\x00'
?
> From: Hans Hübner <hans.huebner(a)gmail.com>
> Subject: [basex-talk] On the client protocol level: Can a query be executed multiple times?
> Date: February 23, 2013 2:41:30 PM CST
> To: basex-talk(a)mailman.uni-konstanz.de
>
>
> I have a question regarding the client protocol: Can a query that has been prepared using the "QUERY" protocol message be executed only once, or multiple times? If it can be executed multiple times, with different parameter sets, how is the previous execution ended? The documentation of the "CLOSE" message seems to indicate the the query is unregistered when it is closed.
>
> Is there some documentation or sample code that illustrates the expected sequence of client messages for query execution?
>
> Thanks,
> Hans