_event

#event

###Send a message event.

Syntax

status = event ( target,method[ ,TVargList[ ,arg1[ ,arg2[ ,argN ] ] ] ] ) ;

Arguments

1. str target

The target, of the form [instance#]concept[.parent][@node]

2. str method

The method for the target to call. The target must have the method enabled.

3. list TVargList(optional)

If an empty list, then the method arguments arg1, arg2, ... , argN follow. If a non-empty list, then the arguments are contained in the TVargList The TVargList argument contains a list of the token/value pairs that are included in the message and passed as arguments to the method being executed on the target. To send a token variable and its values, the token variable should be referenced as &variable. In query messages, when a token is sent without its values, it means that the target should supply the token values in the reply message. To specify a token variable without values, you must either delete all the values in the variable before referencing it or simply put the variable name in quotes (for example, "variable"). In a query message, the STATUS variable is implicitly included as the last token, without a value, so that the target is obligated to return a value for it in the reply message.

4. list arg1(optional)

The first argument. The TVargList must be {}.

5. list arg2(optional)

The second argument. The TVargList must be {}.

6. list argN(optional)

The Nth argument. The TVargList must be {}.

Return Value

str status

• $ACKNOWLEDGE : The message was sent.

The STATUS variable is set to $ACKNOWLEDGE

str status

• $ACKNOWLEDGE : The message was sent.

The STATUS variable is set to $ACKNOWLEDGE

Exceptions

• %ARGUMENT: Invalid arguments. Usage: status = event ( target,method[ ,TVargList[ ,arg1[ ,arg2[ ,argN ] ] ] ] ) ;

Description

The event method returns immediately with no REPLY message.

The query method blocks until one of the following events occur:

• A REPLY message is received. The STATUS variable is set to the value of the STATUS token found in the reply message.

• The _timeout _value is exceeded. The STATUS variable is set to the value "%TIMEOUT". If a timeout handler was defined with the _on_timeout _statement, then it is executed first. If the timeout handler returns a false value, which sets the STATUS variable, then the query method is aborted and returns the value of the STATUS variable.

• The instance _lifetime _is exceeded. The STATUS variable is set to the value %DEATH". If a death handler was defined with the on_death statement, then it is executed first. If the death handler returns a false value, which sets the STATUS variable, then the query method is aborted and returns the value of the STATUS variable.

• An alarm is triggered. The STATUS variable is set to the value "%ALARM". If an alarm handler was defined with the on_alarm statement, then it is executed first. If the alarm handler returns a false value, which sets the STATUS variable, then the query method is aborted and returns the value of the STATUS variable.

• An interrupt (^C) is received. The STATUS variable is set to the value "%INTERRUPT". If an interrupt handler was defined with the on_interrupt statement, then it is executed first. If the interrupt handler returns a false value, which sets the STATUS variable, then the query method is aborted and returns the value of the STATUS variable.

• An pipe signal is received. The STATUS variable is set to the value "%PIPE". If an interrupt handler was defined with the on_pipe statement, then it is executed first. If the pipe handler returns a false value, which sets the STATUS variable, then the query method is aborted and returns the value of the STATUS variable

.

• An hangup signal is received. The STATUS variable is set to the value "%HANGUP". If an interrupt handler was defined with the on_hangup statement, then it is executed first. If the hangup handler returns a false value, which sets the STATUS variable, then the query method is aborted and returns the value of the STATUS variable.

• An EVENT or QUERY message arrives whose method is defined and enabled in the HyperScript program. The STATUS variable is set to the value "%MESSAGE". If a message handler was defined, then it is executed first. The query method is then aborted and returns the value of the STATUS variable. The incoming message will invoke the specified method only when the HyperScript program enters the IDLE state by calling the idle method.

• Death occurred before the reply message was received

CONNECT()
{
  /* Received connect message from sender.*/
  /* Send back confirmation message */
  TEXT = { "Connected to ", self () } ;
  event ( sender(),  "message", { &TEXT } ) ;

  /* Call the setup method to send a query */
  SETUP() ;
  return ;
}

SETUP()
{
  /* Send $recipe and ask for runtime */
  arglist = { &$recipe,  "runtime" } ;

  timeout ( 10 ) ;
  on_timeout return TIMEOUT_HANDLER() ;

  ret = query ( "furn12@dec81z", "SETUP", arglist )  ;

  if ( ret == "%TIMEOUT" ) {
    /* TIMEOUT occurred, message not sent */
  }
}

/* Exit if a timeout occurs */
TIMEOUT_HANDLER
{
  puts "Timeout occurred" ;
  return "%TIMEOUT" ; } ;
}

/* Enable the connect method */
enable CONNECT ;

/* Enter IDLE state and wait for connect message */
idle() ;

Examples

local ;

// Create a little method
list MSG ( str TEXT ) { puts { sender, " sent '",TEXT,"'" } ; } ;

// Enable it so that it can receive messages
enable MSG ;

// Call it locally to see that it works.
TEXT = "internal call" ;
MSG( TEXT );

// This message handle is invoked then the message arrives.
// It accepts the message by returning $ACK
list MESSAGE_HANDLER() {
  on_message return MESSAGE_HANDLER() ;
  return "$ACK" ;
} ;
on_message return MESSAGE_HANDLER() ;

puts "sending first message" ;
TEXT = "call using old-style arguments" ;
event ( self, "MSG", { &TEXT} ) ;

// While sleeping, we'll get the message.
sleep 1 ;
puts "sending second message" ;
TEXT = "call using new-style arguments" ;
event ( self, "MSG", {},  TEXT ) ;
// While sleeping, we'll get the second message.
sleep 1 ;

Related Links

query
timeout