Rclient                package:Rserve                R Documentation

_F_u_n_c_t_i_o_n_s _t_o _t_a_l_k _t_o _a_n _R_s_e_r_v_e

_D_e_s_c_r_i_p_t_i_o_n:

     Rserve is a server providing R functionality via sockets. The
     following functions allow another R session to start new Rserve
     sessions and evaluate commands. The support is very rudimentary
     and uses only a fraction of the funtionality provided by Rserve.
     The typical use of Rserve is to connect to other applications, not
     necessarily to connect two R processes. However, it is not
     uncommon to have a cluster of Rserve machines so the following
     functions provide a simple client access.

     For more complete cilent implementation see 'src/clients'
     directory of the Rserve distribution which show a C/C++ client.
     Also available from the Rserve pages is a Java client
     ('JRclient'). See 'http://rosuda.org/Rserve' for details.

_U_s_a_g_e:

     RSconnect(host = "localhost", port = 6311)
     RSlogin(c, user, pwd, silent = FALSE)
     RSeval(c, expr)
     RSeval.old(c, cmd)
     RSclose(c)
     RSshutdown(c, pwd = NULL)
     RSdetach(c)
     RSevalDetach(c, cmd = "")
     RSattach(session)
     RSassign(c, obj, name = deparse(substitute(obj)) )
     RSassign.old(c, obj, name = deparse(substitute(obj)) )

_A_r_g_u_m_e_n_t_s:

    host: host to connect to

    port: TCP port to connect to

       c: Rserve connection

    user: username for authentication

     pwd: password for authentication

     cmd: command (as string) to evaluate

  silent: flag indicating whether a failure should raise an error or
          not

 session: session object as returned by 'RSdetach' or 'RSevalDetach'

     obj: value to assign

    name: name to assign to on the remote side

    expr: R expression to evaluate remotely

_D_e_t_a_i_l_s:

     'RSconnect' creates a connection to a Rserve. The returned handle
     is to be used in all subsequent calls to client functions. The
     session associated witht he connection is alive until closed via
     'RSclose'.

     'RSlogin' performs authentication with the Rserve. Currently this
     simple client supports only plain text authentication, encryption
     is not supported.

     'RSclose' closes the Rserve connection.

     'RSeval' evaluates the supplied expression remotely. 'expr' can be
     either a string or any R expression. Use 'quote' to use
     unevaluated expressions. The implementation of 'RSeval' is very
     efficient in that it does not require any buffer on the remote
     side and uses native R serialization as the protocol. See exmples
     below for correct use.

     'RSeval.old' is deprecated and present only for compatibility with
     older Rserve implementations. It evaluates the string in the
     remote Rserve and returns the result. Note that you will have to
     load the same packages on both ends if the result is an (S3/S4)
     object such that corresponding classes and methods are available.
     Also note that the result is transported on the network so sending
     huge results can be slow. Thus consider sending only relebant
     parts or keep the results on the other end if pertinent.

     'RSdetach' detaches from the current Rserve connection. The
     connection is closed but can be restored by using 'RSattach' with
     the value returned by 'RSdetach'. Technically the R on the other
     end is still running and waiting to be atached.

     'RSshutdown' terminates the server gracefully. It should be
     immediately followed by 'RSclose' since the server closes the
     connection. It can be issued only on a valid (authenticated)
     connection. The password parameter is currently ignored since
     password-protected shutdown is not yet supported. Please note that
     you should not terminate servers that you did not start.

     'RSevalDetach' same as 'RSdetach' but allows asynchronous
     evaluation of the command. The remote Rserve is instructed to
     evaluate the command after the connection is detached. Please note
     that the session cannot be attached until the evaluation finished.
     Therefore it is advisable to use another session when attaching to
     verify the status of the detached session where necessary.

     'RSattach' resume connection to an existing session in Rserve. The
     'session' argument must have been previously returned from the
     'RSdetach' or 'RSevalDetach' comment.

     'RSassign' pushes an object to Rserve and assigns it to the given
     name. Note that the name can be an (unevaluated) R expression
     itself thus allowing constructs such as 'RSassign(c, 1:5,
     quote(a$foo))' which will result in 'a$foo <- 1:5' remotely.
     However, character names are interpreted literarly.

_A_u_t_h_o_r(_s):

     Simon Urbanek

_E_x_a_m_p_l_e_s:

     ## Not run: 
       c <- RSconnect()
       data(stackloss)
       RSassign(c, stackloss)
       RSeval(c, quote(library(MASS)))
       RSeval(c, quote(rlm(stack.loss ~ ., stackloss)$coeff))
       RSeval(c, "getwd()")
       
       image <- RSeval(c, quote(try({
         attach(stackloss)
         library(Cairo)
         Cairo(file="plot.png")
         plot(Air.Flow,stack.loss,col=2,pch=19,cex=2)
         dev.off()
         readBin("plot.png", "raw", 999999)})))
       if (inherits(image, "try-error"))
         stop(image)
     ## End(Not run)

