Initialize method

Description

VWorks software calls the Initialize method to tell the plugin to initialize a device. The plugin is expected to do everything necessary to bring the device into a state that allows it to accept commands for activities such as opening a serial port, setting the baud rate, or homing a motor.

Note: VWorks software calls the Close method to terminate the connection to the device. See “Close method” .

IMPORTANT The Initialize method should execute synchronously, that is, it should not return until the device initialization is complete.

Syntax

 

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

Parameters

 

CommandXML	[in] An Initialize XML block that contains initialization parameters for the device.
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” .

Initialize method input

VWorks software passes an Initialize XML block into the CommandXML parameter of the Initialize method.

Initialize XML block

VWorks software creates the Initialize XML block as follows:

•	Extracts the device initialization parameters from the Device XML block that was received with a previous call to the GetMetaData method. See “GetMetaData method” .

•	Modifies any parameters that the user changed.

VWorks software then passes the Initialize XML block to the plugin in the CommandXML parameter of the Initialize method.

When the plugin receives the Initialize XML block, it only needs to check the Name and Value attributes of the Parameter 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> <Parameters> <Parameter Name='Profile' ... Value=''> <Ranges> <Range /> ... </Ranges> </Parameter> </Parameters> </Command> </Velocity11>

Parameter element

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

 

Name	Value
Name	The value Profile.
Scriptable	See “Scriptable attribute” .
Style	See “Style attribute” .
Type	See “Type attribute” .
Value	The name of the profile to be used to initialize the plugin.

Example of Initialize method input

The following sample code is an Initialize XML block received by the plugin from VWorks software as a string in the CommandXML parameter of the Initialize method. VWorks software tells the plugin to initialize the device using the profile named My profile.

 

<?xml version='1.0' encoding='ASCII' ?> <Velocity11 file='MetaData' md5sum='674489a50c869a3df216bf989803b350' version='1.0' > <Command Compiler='0' Editor='0' Name='Initialize' NextTaskToExecute='1' →RequiresRefresh='0' TaskRequiresLocation='1' VisibleAvailability='1' > <Parameters > <Parameter Name='Profile' Scriptable='1' Style='0' Type='2' →Value='My profile' > <Ranges > <Range Value='A test profile' /> <Range Value='My profile B' /> <Range Value='My profile C' /> </Ranges> </Parameter> </Parameters> </Command> </Velocity11>

Related information

 

For information about...	See...
Close method	“Close method”
Command XML block	“Command XML block”
GetErrorInfo method	“GetErrorInfo method”
GetMetaData method	“GetMetaData method”
ReturnCode enumerated type	“ReturnCode enumerated type”