Machine Handle Operator

The machine handle operator lets you specify in a convenient, readable way the target machine for a function to be executed by the Agent in a distributed testing environment. Use it to override the default machine specified for the current thread.

For more information about the SYS_File functions that work with target machines, see Functions by Programming Task and About File Handles.

There are two forms for the machine handle operator: arrow (hMachine->) and bracket ([hMachine]).

Arrow Form

To specify a machine handle for a function with the arrow form, type:

hMachine -> distrib_func

Argument	Description
`hMachine`	The machine handle.
`distrib_func`	A call to a SYS_ function or a user-defined function. It can be a method call if the `hMachine` -> syntax starts the line (that is, it is not embedded in a statement). A simple function can be embedded in a statement.

Bracket Form

To specify a machine handle for a function with the bracket form, type:

[hMachine] distrib_func

Argument	Description
`hMachine`	The machine handle.
`distrib_func`	A call to a SYS_ function, to a 4Test function that is not being used to return a value, or to an object-oriented method. The bracket form machine handle operator must be at the beginning of the 4Test statement line.

Examples

[ ] hMachine -> SYS_SetDir ()
[-] [hMachine] SYS_SetDir ()
	[ ] 
[-] for each sMachine in lsMachine
	[ ] [sMachine] TextEditor.Search.Find.Pick 
	[ ] 
[ ] ARRAY[20] of STRING machArray
[ ] // Initialize array
[ ] ...
[-] for INTEGER I = 2 to 5
	[ ] [machArray[i]] TextEditor.Search.Find.Pick

The machine handle operator is useful when a thread driving one machine needs to drive something on a different machine. For example:

[-] for each sMachine in lsMachine
	[ ] spawn // start thread for each sMachine
	[ ] SetMachine (sMachine)
	[ ] // ... code executed on sMachine
[ ] 
[ ] ["server"]doThis() // code executed on "server"
[ ] 
[ ] // ... continue with code for sMachine
[ ] rendezvous

Comparing Bracket and Arrow Forms

The bracket form has the advantage over the arrow form because it allows any expression to supply the machine handle. The arrow form requires the machine handle to be addressable.

Type casting is valid within the machine operator. This means you can specify the string form of the machine name instead of the handle form. Thus the following four statements accomplish the same thing if hMachine is the handle returned by Connect ("MyMachine"):

hMachine -> SYS_SetDir ()
[hMachine] SYS_SetDir ()
"MyMachine" -> SYS_SetDir ()
["MyMachine"] SYS_SetDir ()