NAME

       read-remote -  (distributed-computing)

PURPOSE

       Get results of a service call.

SYNTAX

           read-remote <service> \
               [ data <data> ] \
               [ error <error> ] \
               [ status <status> ] \
               [ status-text <status text> ] \
               [ exit-status <service status> ]

DESCRIPTION

       Use  read-remote to get the results of call-remote created in new-remote; the same <service> must be used
       in all.

       - Getting the reply from server

       The service reply is split in two. One part is the  actual  result  of  processing  (called  "stdout"  or
       standard  output),  and  that  is  "data".  The  other is the error messages (called "stderr" or standard
       error), and that's "error". The standard output goes to "data", except from report-error and print-format
       (with "to-error" clause) which goes to "error". Note that "data" and "error" streams  can  be  co-mingled
       when  output  by  the  service, but they will be obtained separately. This allows for clean separation of
       output from any error messages.

       <data> is the "data" reply of a service call (in "data" clause). <error> is the "error" reply (in "error"
       clause).

       - Getting status of a service call

       The status of a service call (as a number) can be obtained in <status> (in "status" clause). This is  the
       protocol status, and it may be:

           • GG_OKAY if request succeeded,

           • GG_CLI_ERR_RESOLVE_ADDR if host name for TCP connection cannot be resolved,

           • GG_CLI_ERR_PATH_TOO_LONG if path name of Unix socket is too long,

           •  GG_CLI_ERR_SOCKET  if  cannot  create a socket (for instance they are exhausted for the process or
           system),

           • GG_CLI_ERR_CONNECT if cannot connect to server (TCP or Unix alike),

           • GG_CLI_ERR_SOCK_WRITE if cannot write data to server (for instance if  server  has  encountered  an
           error or is down, or if network connection is no longer available),

           •  GG_CLI_ERR_SOCK_READ  if  cannot  read data from server (for instance if server has encountered an
           error or is down, or if network connection is no longer available),

           • GG_CLI_ERR_PROT_ERR if there is a protocol error, which indicates a protocol  issue  on  either  or
           both sides,

           • GG_CLI_ERR_BAD_VER if either side does not support protocol used by the other,

           • GG_CLI_ERR_SRV if server cannot complete the request,

           • GG_CLI_ERR_UNK if server does not recognize record types used by the client,

           • GG_CLI_ERR_OUT_MEM if client is out of memory,

           • GG_CLI_ERR_ENV_TOO_LONG if the combined length of all environment variables is too long,

           • GG_CLI_ERR_ENV_ODD if the number of supplied environment name/value pairs is incorrect,

           • GG_CLI_ERR_BAD_TIMEOUT if the value for timeout is incorrect,

           •  GG_CLI_ERR_TIMEOUT  if  the  request  timed  out  based on "timeout" parameter or otherwise if the
           underlying Operating System libraries declared their own timeout.

       You can also obtain the status text in <status text> (in "status-text" clause); this is a human  readable
       status message which is am empty string (i.e. "") if there is no error (meaning if <status> is GG_OKAY).

       - Getting service status

       <service  status>  (in  "exit-status"  clause) is the return status (as a number) of the code executing a
       remote service handler; it is conceptually similar to a return value from a function (as a  number).  The
       particular  service  handler  you  are  calling  may or may not return the status; if it does, its return
       status can be sent back via exit-status and/or exit-handler statement.

       You must specify at least one value to obtain in read-remote, or any number of them.

EXAMPLES

       See examples in new-remote and call-remote.

SEE ALSO

        Distributed computing

       call-remote new-remote read-remote run-remote See all documentation

$DATE                                               $VERSION                                           GOLF(2gg)