NAME
if_msg_from_server -- wait for message from server
PROTOTYPE
unitptr if_msg_from_server( int iOperands, char *pcServer, float fTimeOut, char *pcMessagePatterns, char *pcOptions, unitptr uHost)
ARGUMENTS
- int iOperands
- makes an operator unit, if > 0
- char *pcServer
- name of server to contact
- float fTimeOut
- time out in seconds
- char *pcMessagePatterns
- message pattern(s)
- char *pcOptions
- - not documented in source --
- unitptr uHost
- host unit
RETURN VALUE:
A pointer to the created unit or NULL in the case of an error.
DESCRIPTION:
Expects to receive a message from server. The message is specified
by one or more template strings. When a matching message has been
sent since the most recent return of the msg_from_server call,
the unit will execute itself and (optionally) its operand units.
Otherwise, the call will block for the specified timeout or the
arrival of a matching message, whatever happens earlier.
If the wait is terminated by the arrival of a matching message,
the operand units will be executed, otherwise only the unit
will return.
Several units can listen to the same message (or overlapping
message sets). A message that matches to several units is
sent to them all.
Each message that comes in while no unit is waiting is buffered
until there is occasion to handle it. That is, messages will not
actively trigger units, they will only set up marks.
If in this way several messages pile up for a unit, up to a
maximal nr of maxmsg (default=1) are kept in a buffer of the
unit. Calling the unit then can either use up one message from
the buffer (detailed mode), or all at once (all-in-one mode).
OPTIONS:
- %a
- set all-in-one mode
- %d
- set detailed mode
- %kM
- set maxmsg to value k
MESSAGE PATTERN:
A message consists of an initial token followed by a blank
followed by arbitrary text. The initial token is matched
to the message pattern following the same rules as explained
for the matching of NST exception types. As there, the
asterisk acts as a wildcard for a field.
The message pattern can specify several white-space separated
message tokens. Example:
abc:* uvwxyz 13:*:44
SUBUNITS:
This unit has one named subunit for each of the following methods
of base class msg_t:
container:get_msg to invoke element function get_msg of msg_t
where container denotes the name that is given to the created unit
after return from this constructor function.
EXECUTION:
Execution of the created unit does nothing. However, execution of
any of its named subunits (via a use_named unit) invokes the
corresponding C class method. The interface of each named
subunit provides inputs and outputs for the corresponding method.
INTERFACE OF NAMED SUBUNITS:
Subunit container:get_msg (invokes element function get_msg of msg_t):
- X_in[1]:
- (input field 0) timeout in seconds
- X_out[1]:
- (output field 0) matching message 0/1=yes/no
- Y_out[]:
- (text string) most recent received message
SEE ALSO:
FILE
/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../remotesrc/nst_remote.c