18.4.0 released Sep 25, 2023
Call server

Purpose: Make a remote server request.

call-server ( <server> [ ,... ] ) | \
                ( <server> [ array-count <array count> ] ) \
    [ status [ define ] <status> ]  \
    [ started [ define ] <started> ] \
    [ finished-okay [ define ] <finished okay> ]

call-server will make FastCGI call(s) as described in a single <server>, a list of <server>s, or an array of <server>s. Unless only a single <server> is specified, each call will execute in parallel with others (as multiple threads).

<server> is a pointer to a variable of type "vv_fc". This variable must have been created with new-server statement.

A <server> call is made to a remote server. "Remote server" means a process accepting requests that is not the same process executing call-server; it may be running on the same or a different computer, or it may be a different process started by the very same application.

- Multiple server calls in parallel
Executing multiple <server> calls in parallel is possible in two ways:
There is no limit on how many <server>s you can call at the same time; it is limited only by the underlying Operating System resources, such as threads/processes and sockets.

- Call status
Optional <status> (in "status" clause) will be VV_OKAY if all <server> calls have each returned VV_OKAY; this means all have started and all have finished with a valid message from the server; or VV_ERR_FAILED if at least one did not (for example if the server could not be contacted, if there was a network error etc.). Note that VV_OKAY does not mean that the reply is considered a success in any logical sense; only that the request was made and a reply was received according to the server protocol.

- Request(s) status
Note that the actual application status for each <server>, as well as data returned and any application errors can be obtained via "request-status", "data"/"data-length" and "error"/"error-length" clauses of read-server statement, respectively.

- Request(s) duration
call-server will wait for all <server> requests to finish. For that reason, it is a good idea to specify "timeout" clause in new-server for each <server> used, in order to limit the time you would wait. Use read-server to detect a timeout, in which case "request-status" clause would produce VV_FC_ERR_TIMEOUT.

- How many calls started and finished
Optional <started> (in "started" clause) will be the number of server calls that have started. Optional <finished okay> (in "finished-okay" clause) is the number of calls that have finished with return value of VV_OKAY as described above. By using <status>, <started> and <finished okay> you may surmise whether the results of call-server meet your expectations.

<status>, <started> and <finished okay> variables can be created with optional "define".

- Performance, security
call-server is faster than call-web because it does not use HTTP protocol in addition to FastCGI; rather it only uses small and binary FastCGI protocol, which is extremenly fast, especially when using Unix sockets on the same machine (see new-server). Note that FastCGI protocol does not have any inherent security built-in; that is part of the reason why it is fast. As such, it is very well suited for remote server calls on the same machine or between networked machines on a secure network.
Examples
This example will connect to local Unix socket file "/var/lib/vv/app_name/sock/sock" (a Vely application named "app_name"), and make a request named "server" (i.e. it will be processed by source code file "server.vely") with URL path of "/op/add/key/2" (meaning with input parameters "op=add" and "key=2"). Then, server reply is read and displayed.
out-header default
// Create single call
new-server define srv location "/var/lib/vv/app_name/sock/sock" \
    method "GET" app-path "/app_name" request-path "/server" \
    url-payload "/op/add/key/2"
// Call single server call
call-server srv finished-okay define sfok
// Get results of a remote server call
read-server srv data define rdata
// Display results
@Data from server is <<p-out rdata>>

If you are connecting to a server via TCP (and not with a Unix socket like in the example above), the "location" clause in new-server might be:
new-server define srv location "192.168.0.28:2400" \
    method "GET" app-path "/app_name" request-path "/server" \
    url-payload "/op/add/key/2"

In this case, you are connecting to another server (running on IP "192.168.0.28") on port 2400. See vf on how to start a server that listens on a TCP port. You would likely use TCP connectivity only if a server you're connecting to is on a different computer.

See also new-server.
See also
Distributed computing
call-server  
delete-server  
new-server  
read-server    
See all
documentation


You are free to copy, redistribute and adapt this web page (even commercially), as long as you give credit and provide a link back to this page (dofollow) - see full license at CC-BY-4.0. Copyright (c) 2019-2023 Dasoftver LLC. Vely and elephant logo are trademarks of Dasoftver LLC. The software and information on this web site are provided "AS IS" and without any warranties or guarantees of any kind.