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 pf-out/pf-url/pf-web (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 "handler-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; it it does, its return status can be sent back via handler-status and/or exit-handler statement.
You must specify at least one value to obtain in read-remote, or any number of them.
