Read server

18.4.0 released Sep 25, 2023

Read server

Purpose: Get results of a server call.

read-server <server> \
    [ data [ define ] <data> ] \
    [ data-length [ define ] <data length> ] \
    [ error [ define ] <error> ] \
    [ error-length [ define ] <error length> ] \
    [ status [ define ] <status> ] \
    [ status-text [ define ] <status text> ] \
    [ request-status [ define ] <request status> ]

Use read-server to get the results of call-server; the same <server> must be used in both.

- Getting the reply from server
The server 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". If the server is Vely, all its 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 server, but they will be obtained separately. This allows for clean separation of output from any error messages.

<data> is the "data" reply of a server call (in "data" clause), <data length> is the number of bytes in <data> (in "data-length" clause). <error> is the "error" reply (in "error" clause), <error length> is the number of bytes in <error> (in "error-length" clause"). Note that a null-byte is always placed at the end of both <data> and <error> as a convenience, however this byte is not counted in <data length> and <error length>.

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

VV_OKAY if request succeeded,
VV_FC_ERR_RESOLVE_ADDR if host name for TCP connection cannot be resolved,
VV_FC_ERR_PATH_TOO_LONG if path name of Unix socket is too long,
VV_FC_ERR_SOCKET if cannot create a socket (for instance they are exhausted for the process or system),
VV_FC_ERR_CONNECT if cannot connect to server (TCP or Unix alike),
VV_FC_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),
VV_FC_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),
VV_FC_ERR_PROT_ERR if there is a protocol error, which indicates a protocol issue on either or both sides,
VV_FC_ERR_BAD_VER if either side does not support protocol used by the other,
VV_FC_ERR_SRV if server cannot complete the request,
VV_FC_ERR_UNK if server does not recognize record types used by the client,
VV_FC_ERR_OUT_MEM if client is out of memory,
VV_FC_ERR_ENV_TOO_LONG if the combined length of all environment variables is too long,
VV_FC_ERR_ENV_ODD if the number of supplied environment name/value pairs is incorrect,
VV_FC_ERR_BAD_TIMEOUT if the value for timeout is incorrect,
VV_FC_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 VV_OKAY).

- Getting request (application) status
<request status> (in "request-status" clause) is the return status (as a number) of the code executing a remote server call; it is similar to a return value from a function. The particular server code you are calling may or may not return the status. If you are calling Vely server code, the return status can be sent back via exit-code statement.

For any of the above values you can obtain with read-server, you can create them with "define" statement. You must specify at least one value to obtain in read-server, or any number of them.

Examples

See examples in new-server and call-server.