references

References and Dereferencing

References and dereferencing share some similarity with their counterparts in the C programming language, but there are differences in syntax and meaning in HS.

References

For a variable V, &V is a "reference to V". That is, a variable assigned to &V holds the str identifier of V, namely "V". For example:

int V = 99;
rV = &V;        /* rV holds a reference to V, namely "V" */

_

It should be apparent that the unary reference operator & is a short-hand way of extracting the name (identifier) of a variable. Thus, the following statement also creates a reference to variable V:

str rV = "V";        /* rV = &V; */

_

However, these two forms of referencing have distinct meanings when used to specify arguments passed in messages, as in the event and query methods. The & reference operator creates a token/value pair in the message, which is passed as data to the target, while the quoted reference creates only the token without a value. The former is intended to specify input arguments to the target, while the latter specify tokens for which data values are returned by the target. For more information, see [Passing Arguments by Reference][2] below, and the topic on [HS Objects][3].

A form of referencing that is unique to [structures][4] is implied whenever an expression evaluates to a structure member name (identifier). For example:

list Date = { int d, int m, int y };        /* Date contains { 'd', 'm', 'y' } */
rDay = Date[0];        			/* rDay contains 'd' */

_

Here, the elements of Date are actually references to the member variables, 'd', 'm', and 'y'.

Dereferencing

The fundamental operation on a reference variable is dereferencing, or referring to the value of the variable referenced. This operation is often called indirection. The dereference operator is (prefix) unary *. From the first example above:

put ( *rV );

_

prints 99.

Similarly, the value of structure member variables can be obtained through dereferencing as follows:

int Day = *Date;        /* Dereference Date.'d' */
int Day = *rDay;        /* Dereference 'd' */
int Month = *Date[1];        /* Dereference Date.'m' */
int Year = *Date[2];        /* Dereference Date.'y' */

_

Indirection can be applied more than once when a variable is a reference to a reference. For example:

int X = { 1, 2, 3 };
int Y = 100;
list L = { &X, &Y };        /* L contains { "X", "Y" } */
Ref = &L[0];        	/* A reference to the first element of L */
rRef = *Ref;        	/* A reference to X, that is "X" */
Xval = **Ref        	/* The value of X, that is { 1, 2, 3 } */

_

Note that L is not a structure, but a list of references to the top-level variables, X, and Y.

The postfix dereferencing operator -> can be used to access members of a structure. For example:

list S2F41 = {
  list L1 = {
    list L2 = {
      int WAFER_COUNT,
      char PPID[10] 
    }
  }
} ; 
ptr = &S2F41.L1.L2 ;

ptr->WAFER_COUNT = totalWafers ;
ptr->PPID = str MINISPEC ;

_

The last two statements in the above example can also be written as:

*ptr.WAFER_COUNT = totalWafers ;
*ptr.PPID = str MINISPEC ;

_

Passing Arguments by Reference

Referenced variables are typically used when sending or receiving messages to [call methods remotely, with arguments][5]. When constructing a message to send with the event or query method, the third argument must be a [list][6] variable where each element in the list defines token/value pairs to include in the message. These token/value pairs become arguments to the method that is called on the target. If a list element is a referenced variable, then that variable and its values are included in the message. However, if the element is a quoted identifier, then only the name will be sent in the message. It is expected that the target object will supply a value for this identifier and return it to the sender.

The following example shows the use of referenced variables to be used as arguments to the disconnect method on the target object; the arglist variable contains references to the TEXT and PAGEWAIT variables.

str TEXT = "Disconnecting from " + self() ;
str PAGEWAIT = "YES" ;
list arglist = { &TEXT, &PAGEWAIT } ;
event ( "target", "disconnect", arglist ) ;

_

Referenced variables are also used when receiving messages. The variable, args, contains a list of the variable names received in the incoming [EVENT][7] or [QUERY][8] message. For example:

The received message:

|target|event|connect|sender||LOTIDS|12000.1|12001.1||EQPID|DVF16F|

initiates a call to the connect method on target, and creates and initializes the following variables:

LOTIDS = { "12000.1", "12001.1" } ;
EQPID = "DVF16F" ;
args = { &LOTID, &EQPID } ;

_

The following code segment demonstrates how to view the message tokens and values:

connect() {
  t = 0 ;
  while ( t < count ( args ) ) {
    put ( "Token = " + args[t] ) ;
    v = 0 ;
    while ( v < count ( *args[t] ) ) {
      put ( " Value = " + (*args[t])[v] ) ;
      v = v + 1 ;
      }
    t = t + 1 ;
    }
  }
}

_

When the code is executed, the output will be:

Token = LOTIDS
Value = 12000.1
Value = 12001.1
Token = EQPID
Value = DFV16F

_

[2]: #Passing Arguments [3]: /docs/language/objects.php [4]: /docs/language/structures.php [5]: /docs/language/objects.php#Calling%20Methods%20Remotely [6]: /docs/language/lists.php [7]: /docs/language/events.php#EVENT [8]: /docs/language/events.php#QUERY