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