gsio.Rdgsio.connect connects to the Messenger server according
to the host and port arguments. Typically you want
to call gsio.greeting() on the resulting connection to
start the communication.
gsio.msg sends a message to the Messenger and waits for a response.
Any unmatched, named arguments in ... will be ignored. As a special case,
passing NULL will tell gsio.msg to not send any message,
but still process any pending replies (useful with wait=FALSE to
check for such condition).
gsio.greeting receives a greeting response from the Messenger,
i.e., the first response after connecting.
The close method closes the connection to the GenStat Messenger.
The following functions are low-level and typically not used directly
(use gsio.msg instead): gsio.send sends content to the
Messenger, gsio.recv receives a reply from the Messenger.
gsio.connect(host = "localhost", port = 8085L, timeout = 1)
gsio.send(io, ...)
gsio.recv(io, wait = TRUE)
gsio.msg(io, ..., all = TRUE, wait = TRUE)
# S3 method for class 'gsio'
close(con, ...)
gsio.greeting(io)string, name (or IP address) or the host to connect to
integer, TCP port to connect to
real, time (in seconds, can be fractional) for communication attempts.
"gsio" object as obtained from gsio.connect()
content to send, will be pasted together as string without a separator.
logical scalar, if TRUE then this function does not return until
a reply is received. Otherwise will return NULL if no reply was recevied.
Note that if a response header is recevied, the function will still wait until it can read
the entire response in order to prevent inconsistent state of the connection.
logical scalar, if TRUE then all replies until "STAT" is
received with be collected and returned at the end in a list. Note that if
"STAT" is the only reply when the list will be empty. If FALSE
then only the first reply will be returned.
"gsio" object as obtained from gsio.connect()
gsio.connect: an object of the class "gsio" which
can be used for subsequent communication.
gsio.send: undefined (currently NULL)
gsio.recv: Either NULL (if wait=FALSE and no reply is present) or a
a reply (see gsio.msg return description below for the definition of a reply).
gsio.msg: If all=TRUE then a list of replies, otherwise a single reply.
A reply is a list with the components "cmd" (command), "type" (content type)
and "content".
Most common commands are "OUT" (text output), "GRAPH" (plot output) and
"STAT" (end of evaluation, "status" change).
Common types are "TEXT", "RTF" and "HTML" for text output
types, "PNG" for graph output and "NULL" if the reply has no contents.
gsio.greeting: Greeting reply contents.
Messenger verisons 1.1 and higher will reply with a list at least
with the components version and outputType. The latter can have
values "TEXT", "HTML" and "RTF". Older versions will only
return a string.
A typical communication with the Messenger starts with
gsio.connect(), followed by gsio.greeting(), one or more
calls to gsio.msg() and final close().
In most cases the messages to sent to the Messenger are strings
representing code to evaluate in GenStat.
Since Messenger 1.1 there are special commands that will be interpreted
by the Messenger instead of passing them to GenStat. Those messages start
with "#:". Should you need to send a string to GenStat that also
starts with "#:" (uncommon) then precede the string with "#:"
to tell the Messenger that it should be passed through, so "#:#:FOO"
will result in "#:FOO" being sent to GenStat.
Which special commands are supported depends on the Messenger version.
As of 1.1 "#:SET_OUTPUT_TYPE:HTML" will set the output type
(valid values are TEXT, RTF and HTML) and restart
GenStat with the new setting. "#:RESTART" will restart the
GetStat server without changing the current output settings. NOTE: In both
cases the GetStat server currently sends two STAT responses,
so it is prudent to call gsio.recv(c, wait=FALSE) immediately after
receiving the message response to clear the extra STAT response.
link{gsio.msg()}