BarCodeRead method

Event

A barcode read occurred.

Description

VWorks software calls the BarCodeRead method after a barcode read occurs. The plugin must tell VWorks software what action to take if a barcode is present on one of the labware’s four sides.

Plugins can also use this method to determine if a barcode is expected or valid.

Syntax

 

HRESULT BarCodeRead( [in] BSTR sXML, [in, out] BSTR* sResultXML );

Parameters

 

sXML	[in] A Velocity11 XML element containing information about the labware that was involved in the barcode read.
sResultXML	[in, out] A Velocity11 XML element or a HookResults XML block that specifies the action to take if a barcode is present on one of the labware’s four sides. See “HookResults XML block” .

BarCodeRead method input

VWorks software passes a Velocity11 XML element into the sXML parameter of the BarCodeRead method. This XML element provides information about the labware involved in the barcode read.

Velocity11 element

The Velocity11 element has the following attributes:

 

Name	Value
NorthBarcode	The barcode if it is located on the north side of the labware.
SouthBarcode	The barcode if it is located on the south side of the labware.
WestBarcode	The barcode if it is located on the west side of the labware.
EastBarcode	The barcode if it is located on the east side of the labware.
PlateName	The labware name.
InstanceNumber	The labware instance number.
DatabaseID	The database ID of the labware.
Plugin	The name of the plugin.
Labware	The labware type.
Device	The device name.
Location	The name of the location on the device where the barcode read occurred.
Path	The name of the protocol that generated the event. 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.

Example of BarCodeRead method input

The following sample code is a Velocity11 XML element that is received by the plugin from VWorks software as a string in the sXML parameter of the BarCodeRead method. VWorks software tells the plugin that a barcode read occurred on the south side of the tip box named NameofPlate.

 

<?xml version='1.0' encoding='ASCII' ?> <Velocity11 file='MetaData' md5sum='849392019ca47102839e845113d11840' version='1.0'> < BarCodeRead NorthBarcode='BAR0001' SouthBarcode='BAR0002' WestBarcode='BAR0003' EastBarcode='BAR0004' PlateName='NameofPlate' InstanceNumber='1' DatabaseID='1' Labware='384 V11 ST10 Tip Box 10734.102' Device='NameofDevice' Location='NameofLocation' Path='C:\VWorks Workspace\Protocols\protocol1.pro'/> </Velocity11>

BarCodeRead output

The plugin returns either a Velocity11 XML element or a HookResults element in the sResultXML parameter of the BarCodeRead method as follows:

 

Action VWorks software should take	Output type	Action or ResultType attribute value
Send the labware to the quarantine device.	Velocity11 XML element	Action=BCR_QUARANTINE
Ignore the error and continue as if the misread has not occurred.	Velocity11 XML element	Action=BCR_IGNORE
Write a message to the Main Log.	HookResults XML block	ResultType=LogMessage or ResultType=LogError
Pause the scheduler.	HookResults XML block	ResultType=PauseExecution

Velocity 11 element (Velocity11 XML element)

For the Velocity11 XML element, the Velocity11 element has the following attributes plus the md5sum and version attributes:

 

Name	Value
file	The value BarCodeReadResult.
Action	Specifies the action to take after a barcode read occurs. Possible values: • BCR_QUARANTINE Send the labware to the quarantine device. • BCR_IGNORE Take no action.

Velocity 11 element (HookResults XML block)

For the HookResults XML block, the Velocity11 element has the following additional attribute:

 

Name	Value
Action	Specifies the action to take after a barcode read occurs. Possible values: • BCR_QUARANTINE Send the labware to the quarantine device. • BCR_IGNORE Take no action.

Example of BarCodeRead method output (Velocity11 XML element)

The following sample code is a Velocity11 element that is returned to VWorks software by the plugin as a string in the sXML parameter of the BarCodeRead method. The plugin tells VWorks software to take no action after a barcode read occurs.

 

<?xml version='1.0' encoding='ASCII' ?> <Velocity11 file='BarCodeReadResult' md5sum='52226bb1b70c756162b551f1f5685a5d' version='1.0' Action='BCR_IGNORE' />

Example of BarCodeRead method output (HookResults XML block)

The following sample code is a HookResults XML block that is returned to VWorks software by the plugin as a string in the sXML parameter of the BarCodeRead method. (See “HookResults XML block” .) The plugin tells the scheduler to pause the protocol. The plugin also tells VWorks software to quarantine the labware and to write the following Error-type message to the Main Log:

Plugin pause: Barcode is not in the database.

 

<?xml version='1.0' encoding='ASCII' ?> <Velocity11 file='MetaData' md5sum='52226bb1b70c756162b551f1f5685a5d' version='1.0' Action='BCR_QUARANTINE'> <HookResults> <Results> <HookResult ResultType='LogError' ResultValue='Plugin paused: Barcode is not in the database.' /> <HookResult ResultType='PauseExecution' ResultValue='True' /> </Results> </HookResults> </Velocity11>

Related information

 

For information about...	See...
BarCodeMisread method	“BarCodeMisread method”
HookResults XML block	“HookResults XML block”