GOLF(2gg)

💖 GOLF(2gg) 💖

okay bestie, welcome to the Development section of the GOLF(2gg) manual — yes that's the whole vibe, we're in the dev pages now, grab a boba 🧋

---

✨ NAME ✨

read-remote — (distributed-computing) 🦋

---

🎀 PURPOSE 🎀

Get results of a service call. that's it. that's the goal. slay. 💅

---

🌸 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. like, same service everywhere or it's not gonna work, no cap. 🫶

🍓 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 the to-error clause) which goes to error. ngl that's the little plot twist 🙈

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. iconic behaviour honestly ✨

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

🦋 Getting status of a service call

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

• GG_OKAY if request succeeded — the good ending 💖
• 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 the 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 the 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). so like, empty string = we're chilling 😌

🌈 Getting service status

<service status> (in the 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.

lowkey important: you must specify at least one value to obtain in read-remote, or any number of them. like, at least one bestie, we can't read nothing 🙈

---

🌟 EXAMPLES 🌟

See examples in new-remote and call-remote. (go look, they eat 💅)

---

👑 SEE ALSO 👑

Distributed computing

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

---

and that's the whole page bestie, hope it ate 💖 version $VERSION, dated $DATE, straight from the GOLF(2gg) manual — mwah, study safe, drink water, and remember: separate your data from your error 😭🌸