SetMachineData Function

Action

Sets the named data to the specified value and associates it with the specified machine.

Syntax

SetMachineData (hMachine, sName, aData)

Variable	Description
`hMachine`	The handle to the machine for which to set machine data. HMACHINE. Since a string specifying the Agent name for the machine is automatically cast to a legal handle for the machine, you can also supply such a string for this argument.
`sName`	The name of this machine data—to be used subsequently to retrieve the data. STRING.
`aData`	The data to be associated with this machine. ANYTYPE.

Variable

Description

hMachine

The handle to the machine for which to set machine data. HMACHINE.

Since a string specifying the Agent name for the machine is automatically cast to a legal handle for the machine, you can also supply such a string for this argument.

sName

The name of this machine data—to be used subsequently to retrieve the data. STRING.

aData

The data to be associated with this machine. ANYTYPE.

Notes

Pass NULL for hMachine to specify the current machine for the current thread.

You can think of machine data as being a global variable associated with the specified machine. You provide a name for the variable so you can subsequently retrieve the data and you initialize the variable with data of any type, including a user-defined type. You can set the data or retrieve the data multiple times. You can set multiple pieces of data with different names for the same machine.

Because the machine data is global, any thread in the current script can use any machine data name to retrieve the associated data, as long as the owning machine is still connected. Because you also have to supply the machine name to retrieve machine data, the data name does not have to be unique for each machine.

Machine data is freed when the script disconnects from that machine.

Example

SetUp (STRING sMach1, STRING sTestState)

// set machine data called "State" to 3d arg.’s value 
SetMachineData (sMach1, "State", sTestState)