methods

HS Methods

A method is a user defined function that can be executed in three ways:

• directly, from a program statement.
• indirectly, in response to an incoming EVENT or QUERY message.
• remotely, by calling the event or query method.

A method cannot be called until it is defined.

Defining Methods

A method definition both declares the method and defines the body of the method. A method can be declared with any of the supported [data types][4], can have arguments, and can return a value. For example:

int M( int i ) { return ( i + 99 ); }        /* Define method M */

A method can be undefined (removed) using the undef statement. For example:

undef M;        /* M is now undefined */

_

The method, M, must be defined to be used again.

Returning Values

The method data type determines what type of value is returned. Any value explicitly returned by the method will get converted to the defined data type. If the method data type is undefined, it defaults to type list.

Methods return values in one of two ways:

• assigning a value to the method name.
• with the return statement.

For example, this method definition for M is equivalent to the one above:

int M( int i ) { M = i + 99; }        /* Assign the return value to M */

_

If no return value is specified, a default value is returned. If the method data type is list or str, the method returns the default value, "$ACKNOWLEDGE". If the method data type is a numeric type (e.g. int, hex, float), the method returns the default value, 1.

Argument Passing

Method arguments are optional. When defined, method arguments control the manner in which passed arguments are received. When the scope of HS is global, method arguments are also global variables. When the scope of HS is local, method arguments are local variables in the method. Regardless of whether method arguments are defined, variables can always be passed as arguments. A special variable, args, contains a list of all the variable arguments that were passed. For example:

/* Define M with one argument */
int M( int i ) { put ( args ); }        /* Print the arguments passed to M */

/* Call M with one argument */
M ( 20 );        			/* Prints "i" */
put ( i );        			/* Prints 20 */

/* Call M with additional arguments */
int j;
int k;
M ( { 1, 2, 3 }, j, k );        	/* Prints "i" "j" "k" */
put ( i );        			/* Prints 1 2 3 */

Note that arguments are passed transparently when a method is invoked by an incoming EVENT or QUERY message. The arguments passed to the method are the token/value pairs sent with the message, and can be accessed in the args variable.

When a method is called, the passed (source) arguments are merged with the defined (destination) arguments according to the following rules:

1. The source arguments are merged into the destination arguments in parallel (see also: the merge method). For each argument merged, if there are more source values than destination values, and if the destination argument is a fixed size, the extra source values are ignored. Otherwise the extra source values are appended to the destination arguments' values. If there are more destination values than source values, the extra destination values are unchanged. If the destination argument is a single vector or list, then all source arguments will merge into the destination argument elements.
2. If an element of the destination vector or list is a literal, then its value is replaced by the corresponding source value.
3. If a source argument is an undeclared variable (as could happen when the arguments originate from an event message, for example), then a new destination variable is declared and initialized with the contents of the source.
4. If a source argument is a declared variable, then the merge procedure is done recursively on the destination argument elements with the source argument elements.

Methods and Events

A method can be invoked by an incoming EVENT or QUERY message if the method has been enabled and the program is in the IDLE state (see the idle method). Method arguments are extracted from the token/value pairs contained in the message, and are merged into the destination arguments as described above.

Similarly, a method can be invoked on a remote target by calling the event or query method.

For details, see HS Events, and HS Objects.