NAME
use_remote -- access NST unit in remote server
PROTOTYPE
unitptr nst_use_remote( char *pcServer, char *pcPath, char *pcOptions, unitptr uHost)
ARGUMENTS
- char *pcServer
- name of remote server. May not be NULL
- char *pcPath
- path of remote unit to use. May not be NULL
- char *pcOptions
- options. May be NULL
- unitptr uHost
- host unit
SYNOPSIS:
Creates a proxy for a remote unit in a server with name pcServer.
The remote unit is identified with the name chain pcPath (e.g.,
pcPath = name1:name2:name3 for sub-sub-unit name3 in named
container name2 in named container name1 in the top-level
circuit). When executed (adapted/ctr'lled) the proxy will send
its input pin values to the remote unit, execute (adapt/ctrl)
it, and fetch the result values back. After that, the former
inputs of the remote unit are restored (but the newly computed
output values are kept).
SERVER NAME AND COMMUNICATION PROTOCOL:
A server name a.b.c.d:portnr selects the TCP protocol with
server address a.b.c.d and port number portnr. Alternatively,
one may also use the form hostname:portnr.
Any other server name name selects the UNIX protocol via
a socket name (this restricts communication to within a
file system).
Remote server and local client must use the same representation
for int and float values (however, this is checked and an error
message issued when the check fails).
INTERFACE:
When a unit of that name exists in the server, the proxy
will carry the subset of those pins of the remote unit that
are from the basic NST data types (scalar,byte,int,float,string).
(units with other, e.g., class-valued pins, can be used, but
the client cannot transfer any data to/from their non-standard pins).
When the proxy mirrors (except for the non-standard pins)
the interface of the remote unit in this way, it will be
said to be in state INTERFACE_MATCH. Only in this state are
execution, adaptation and control operations transmitted to
the remote unit.
In Neo, a successful contacting of the remote unit named xxx
is indicated by a label remote_xxx on the proxy. If the
remote_unit could not be contacted, the label is instead
use_remote.
When no remote unit of the given name can be found (because it
does not exist or the server is not up) the created unit will
be pinless (or will have its previous interface, when the remote
unit still existed). The corresponding states are INTERFACE_MISMATCH,
NO_REMOTE_UNIT or NO_CONNECTION, resp. When the server comes up
later, then the proxy will try to readjust its interface and state
appropriately (similar to the use_method unit).
INITIALIZATION:
When the server and the remote unit are available during creation
of the use_remote instance, the current values of the input
and output pins will be fetched from the server and used
to initialize the corresponding pins of the created proxy.
EXECUTION:
When the client executes (adapts,controls) its proxy, and the
proxy is in the state INTERFACE_MATCH, the following steps happen:
1.the input values of all pins of the proxy are temporarily
copied into the corresponding pins of the remote unit
2.the remote unit is executed (adapted,controlled)
3.the new values in the output pins of the remote unit
are transferred back into the corresponding pins of the
proxy.
4.the original inputs of the remote unit are restored.
(but the changed output values are kept).
EXCEPTIONS:
When the remote unit causes a NST-exception (and does not catch it
itself), it is propagated to the client proxy, so that the client
circuit can react properly.
ADAPTATION:
Analogous to execution.
CONTROL MODES:
Will all be passed to the remote unit, however, a subset of control
modes that are only meaningful locally are filtered out:
...
TIMEOUT OPTION:
An option string %1.5t will specify a time-out of 1.5 seconds for
each execution (adaptation/ctrl) call. When no response from the
server arrives during that time, the operation will simply return
and ignore any replies that may come in later. This can be used
to prevent blocking. However, the current implementation can only
prevent blocking on the first call. After an unsuccessful time-out
subsequent operations are unreliable.
OPTIONS:
- %v
- switches the server to verbose mode.
- %V
- switches the server to very verbose mode.
- %>
- requests oneway transmission: is always non-blocking
and no result data will be received back.
- %Dt
- sets max. time delay D after which response is
expected. If D is missing, the default is 3sec.
D=0 or D<0 is taken as infinity.
- %a
- also send adapt calls, but without transmitting
any pin data.
- %A
- send full adapt calls, including pin data.
- %c
- also send control calls, but without transmitting
any pin data.
- %C
- send full control calls, including pin data.
- %f,%F
- transmit only data to free (=unconnected)
remote inputs. %f will temporarily map the data,
%F will permanently copy. Without %f and
%F mode will be to temporarily map all remote
inputs.
RETURN VALUE:
A pointer to the created unit or NULL in the case of an error.
SEE ALSO:
nstserver.so, appserver.so
FILE
/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../remotesrc/nst_remote.c