NAME

       call-remote -  (distributed-computing)

PURPOSE

       Make a remote service call.

SYNTAX

           call-remote <service> [ ,... ]   \
               [ status <status> ]  \
               [ started <started> ] \
               [ finished-okay <finished okay> ]

DESCRIPTION

       call-remote  will make service call(s) as described in a single <service> or a list of <service>s. Unless
       only a single <service> is specified, each call  will  execute  in  parallel  with  others  (as  multiple
       threads).  call-remote  finishes  when all <service> calls do. Each <service> must have beed created with
       new-remote.

       A <service> call is made to a remote service. "Remote service" means a process accepting requests that is
       not the same process executing call-remote; 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 service calls in parallel

       Executing  multiple  <service> calls in parallel is possible by specifying a list of <service>s separated
       by a comma.

       There is no limit on how many <service>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

       <status>  number  (in "status" clause) will be GG_OKAY if all <service> calls have each returned GG_OKAY;
       this means all have started and all have finished with a valid message from the service; or GG_ERR_FAILED
       if at least one did not (for example if the service could not be contacted, if there was a network  error
       etc.);  or  GG_ERR_MEMORY  if  out  of  memory;  or GG_ERR_TOO_MANY if there is too many calls (more than
       1,000,000).

       Note that GG_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 service protocol.

       - Request(s) status

       Note  that the actual application status for each <service>, as well as data returned and any application
       errors can  be  obtained  via  "exit-status",  "data"  and  "error"  clauses  of  read-remote  statement,
       respectively.

       - Request(s) duration

       call-remote will wait for all <service> requests to finish. For that reason, it is a good idea to specify
       "timeout"  clause  in  new-remote for each <service> used, in order to limit the time you would wait. Use
       read-remote to detect a timeout, in which case "exit-status" clause would produce GG_CLI_ERR_TIMEOUT.

       - How many calls started and finished

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

       - Performance, security

       call-remote  is faster than call-web because it does not use HTTP protocol; rather it only uses small and
       binary protocol, which is extremenly fast, especially when using Unix sockets on the  same  machine  (see
       new-remote).  Note that the binary 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 service 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/gg/app_name/sock/sock" (a Golf application
       named "app_name"), and make a request named "server" (i.e. it will  be  processed  by  source  code  file
       "server.golf")  with  URL  path  of "/op=add/key=2" (meaning with input parameters "op=add" and "key=2").
       Then, service reply is read and displayed.

           // Create single call
           new-remote srv location "/var/lib/gg/app_name/sock/sock" \
               method "GET" app-path "/app_name" request-path "/server" \
               url-params "/op=add/key=2"
           // Call single service call
           call-remote srv finished-okay sfok
           // Get results of a remote service call
           read-remote srv data rdata
           // Display results
           @Data from service is <<print-out rdata>>

       If you are connecting to a service via TCP (and not with a Unix socket like in the  example  above),  the
       "location" clause in new-remote might be:

           new-remote srv location "192.168.0.28:2400" \
               method "GET" app-path "/app_name" request-path "/server" \
               url-params "/op=add/key=2"

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

       See also new-remote.

SEE ALSO

        Distributed computing

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

$DATE                                               $VERSION                                           GOLF(2gg)