Command method

Note: Throughout this guide, when the word command refers to a task in the user interface, the word task is used instead of command.

Description

VWorks software calls the Command method to tell the plugin to execute the specified task.

IMPORTANT Plugins must implement the Command method if the device has any associated tasks. The plugin should not return until the task is completed.

Syntax

 

HRESULT Command( [in] BSTR CommandXML, [out,retval] enum ReturnCode *retVal );

Parameters

 

CommandXML	[in] A Command XML block that describes the task to be executed.
retVal	[out, retval] Returns an error code. Possible values: 0 = The request was completed (RETURN_SUCCESS) 1 = Something was wrong with the input, so the request was not completed (RETURN_BAD_ARGS) 2 = The request was not completed (RETURN_FAIL) For more information, see “ReturnCode enumerated type” .

Command method input

VWorks software passes a Command XML block into the CommandXML parameter of the Command method.

Command XML block

The Command XML block contains the Command element and all its children. This XML block describes the task to be executed.

When the plugin receives the Command XML block, it only needs to check the following attributes:

•	Name attribute of the Command element

•	Name and Value attributes of each Parameter element

•	Value attribute of each Locations element’s child Value element

These attributes are designated by bold text in the following XML structure and input example.

Although VWorks software passes other XML metadata in the Command XML block, this information is of no interest to the plugin.

XML structure

The value of the file attribute for the Velocity11 element is MetaData. See “Velocity11 element” .

 

<?xml version='1.0' encoding='ASCII' ?> <Velocity11> <Command ... Name='' ...> <Parameters> <Parameter ... Name='' ... Value='' > <Ranges> <Range /> ... </Ranges> </Parameter> ... </Parameters> <Locations> <Value Value='' /> ... </Locations> </Command> </Velocity11>

Command element

The Command element has two children: Parameters and Locations. The Command element has the following attributes:

 

Name	Value
Compiler	See “Compiler attribute” .
Description	The description of the task.
Editor	See “Editor attribute” .
Name	The name of the task.
NextTaskToExecute	See “NextTaskToExecute attribute” .
ProtocolName	The name of the protocol that contains the task. If the protocol has been saved, the value of this attribute is the protocol’s file path. If the protocol has not been saved, the value is the default protocol name.
RequiresRefresh	See “RequiresRefresh attribute” .
TaskRequiresLocation	See “TaskRequiresLocation attribute” .
VisibleAvailability	See “VisibleAvailability attribute” .

Parameters element

The Parameters element contains one or more Parameter elements.

Parameter element

The Parameter element contains one Ranges element and has the following attributes:

 

Name	Value
Description	The description of the parameter.
Name	The name of the parameter.
Scriptable	See “Scriptable attribute” .
Style	See “Style attribute” .
Type	See “Type attribute” .
Value	See “Value attribute” .

Locations element

The Locations element contains one of more Value elements.

Value element

Each Value element contains the name of a location that can be used by the task. This element has the following attribute:

 

Name	Value
Value	The name of a location that can be used by the task.

Example of Command method input

The following sample code is a Command XML block that is received by the plugin from VWorks software as a string in the CommandXML parameter of the Command method. VWorks software tells the plugin to execute the Execute method task at the location named Location.

 

<?xml version='1.0' encoding='ASCII' ?> <Velocity11 file='MetaData' md5sum='9e0e9dcbdbb460a7d444cba2a2d0a474' version='1.0' > <Command Compiler='0' Description='Execute a method' Editor='2' →Name='Execute method' NextTaskToExecute='1' ProtocolName='Protocol File - 1' →RequiresRefresh='0' TaskRequiresLocation='1' VisibleAvailability='1' > <Parameters > <Parameter Description='Method name' Name='Method name' Scriptable='1' →Style='0' Type='2' Value='a.lmeth' > <Ranges > <Range Value='a.lmeth' /> </Ranges> </Parameter> </Parameters> <Locations > <Value Value='Location' /> </Locations> </Command> </Velocity11>

Related information

 

For information about...	See...
GetErrorInfo method	“GetErrorInfo method”
ReturnCode enumerated type	“ReturnCode enumerated type”