BenchCel Microplate Handler User Guide : BenchCel ActiveX control : Methods
Methods
Abort
LONG Abort()
Description
Method to clear an error and state information.
Parameters
None
Returns
S_OK if success; other value otherwise
Visual C++ example
m_BenchCel.Abort();
Visual Basic example
BenchCel.Abort
AboutBox
void AboutBox()
Description
Shows a small window that indicates some version information.
Parameters
None
Returns
None
Visual C++ example
BenchCel.AboutBox()
Visual Basic example
m_BenchCel.AboutBox();
Close
void Close()
Description
Method to disconnect from the BenchCel device.
Parameters
None
Returns
None
Visual C++ example
m_BenchCel.Close();
Visual Basic example
BenchCel.Close
Delid
LONG Delid(BSTR DelidFrom, BSTR DelidTo, LONG nRetractionCode)
Description
Method used to remove a lid from a microplate. You will need to specify where the microplate is located and where to place the lid once it is removed from the microplate.
Parameters
 
Argument Type
Argument Name
Range
Description
BSTR
DelidFrom
Available teachpoints
Name of teachpoint where the microplate with the lid is located.
BSTR
DelidTo
Available teachpoints
Optional. Name of teachpoint to place the lid after it has been removed from the microplate.
The BenchCel robot will hold onto the lid if the DelidTo parameter is empty.
LONG
nRetraction Code
0–3
How to position the robot arms after delidding the microplate, where
0– Do nothing
1– Retract normally
2– Not supported
3– Not supported
Returns
S_OK if successful; other value if there was an error.
EnumerateProfiles
VARIANT EnumerateProfiles()
Description
Method to retrieve a list of defined profiles. The strings in this array are the options that should be used for Initialize.
Parameters
None
Returns
An array of profile names.
Visual C++ example
VARIANT vPRofiles = m_BenchCel.EnumerateProfiles();
SAFEARRAY *psa = vProfiles.parray;
BSTR* bstrArray;
if
(FAILED(SafeArrayAccessData(psa,reinterpret_cast<void**>( &bstrArray))))
{
VariantClear(&vProfiles);
return;
}
for (ULONG i = 0; i < psa->rgsabound[0].cElements; i++)
{
MessageBox(CString(bstrArray[i])));
}
SafeArrayUnaccessData(psa); VaraintClear(&vProfiles);
Visual Basic example
profileNames = BenchCel.EnumerateProfiles()
For i = LBound(profileNames) To UBound(profileNames)
MsgBox profileNames(i)
Next
GetFirmwareVersion
BSTR GetFirmwareVersion()
Description
Method to programmatically retrieve firmware version of the device.
Parameters
None
Returns
A version string.
Visual C++ example
CString strFirmVer = m_BenchCel.GetFirmwareVersion();
Visual Basic example
Version = BenchCel.GetFirmwareVersion()
GetLabwareNames
VARIANT GetLabwareNames()
Description
Method to retrieve a list of defined labware. The strings in this array are the options that should be used for SetLabware.
Parameters
None
Returns
An array of labware names.
Visual C++ example
VARIANT vLabware = m_BenchCel.GetLabwareNames();
SAFEARRAY *psa = vLabware.parray;
if
(FAILED(SafeArrayAccessData(psa, reinterpret_cast<void**>( &bstrArray))))
{
VariantClear(&vLabware);
return;
}
for (ULONG i = 0; i < psa->rgsabound[0].cElements; i++)
{
MessageBox(CString(bstrArray[i])));
}
SafeArrayUnaccessData(psa); VariantCLear(&vLabware);
Visual Basic example
LabwareNames = BenchCel.GetLabwareNames
For i = LBound(labwareNames) To UBound(labwareNames)
MsgBox labwareNames(i)
Next
GetLastError
BSTR GetLastError()
Description
Method to retrieve a text message explaining the last error. This method can be called in blocking mode, after a command returns with a failure code, or in non-blocking mode, after the Error event has been fired.
Parameters
None
Returns
An error string.
Visual C++ example
strError = m_BenchCel.GetLastError();
Visual Basic example
strError = BenchCel.GetLastError()
GetStackCount
LONG GetStackCount(LONG *pCount)
Description
Method to retrieve the number of stacks on the BenchCel device. This method must be called after a successful connection in order for it to indicate the current number.
Parameters
 
Argument Type
Argument Name
Range
Description
LONG*
pCount
Valid pointer to receive the stack count
If successful, the value pointed to by pCount should indicate the number of stacks the device has
Returns
S_OK if successful; other value otherwise.
Visual C++ example
1Result = m_BenchCel.GetStackCount(&numStacks);
Visual Basic example
1Result = BenchCel.GetStackCount(numStacks)
GetTeachpointNames
VARIANT GetTeachpointNames()
Description
Method to retrieve the teachpoints known to the device. This method must be called after initialization is complete and it returns an array of available teachpoints, including the stackers.
Parameters
None
Returns
A safe array of teachpoint names.
Visual C++ example
VARIANT vTeachpoints = m_BenchCel.GetTeachpointNames();
SAFEARRAY *psa = vTeachpoints.parray;
BSTR* bstrArray;
if
(FAILED(SafeArrayAccessData(psa,reinterpret_cast<void**>( &bstrArray))))
{
VariantClear(&vTeachpoints);
return;
}
for (ULONG i = 0; i < psa->rgsabound[0].cElements; i++)
{
MessageBox(CString(bstrAdday[i])));
}
SafeArrayUnaccessData(psa);VariantClear(&vTeachpoints);
Visual Basic example
TeachpointNames = BenchCel.GetTeachpointNames
For i= LBound(teachpointNames) To UBound(teachpointNames)
MsgBox teachpointNames(i)
Next
GetVersion
BSTR GetVersion()
Description
Method to programmatically retrieve the version of the ActiveX.
Parameters
None
Returns
A version string.
Visual C++ example
CString strVersion = m_BenchCel.GetVersion();
Visual Basic example
Version = BenchCel.GetVersion()
Ignore
LONG Ignore()
Description
Method to ignore the previously issued error. This is not a recommended course of action, as the errors are issued for a reason. However, ignoring some errors, such as “Plate is rotated”, can be appropriate if the operator understands the implications.
Parameters
None
Returns
S_OK if success; other value otherwise.
Visual C++ example
m_BenchCel.Ignore();
Visual Basic example
BenchCel.Ignore
Initialize
LONG Initialize(BSTR Profile)
Description
Method to connect to the BenchCel device. A BenchCel profile specifies how to connect to the device (serial or Ethernet; if Ethernet, which device on the network and if serial, which port to use) and which teachpoint file to use. If this is called in non-blocking mode, the client application should wait for InitializeComplete before calling other methods. This method should be called before most other methods.
Parameters
 
Argument Type
Argument Name
Range
Description
BSTR
Profile
Valid profile name
The name of the profile to be used for initialization
Returns
S_OK (0) on success; other value otherwise.
Visual C++ example
LONG1Result =
m_BenchCel.Initialize("ethernet");
Visual Basic example
LONG1Result =
BenchCel.Initialize("ethernet")
IsConnected
LONG IsConnected()
Description
Method used to check whether a connection to the BenchCel device is established. The BenchCel device is ready to process commands from the BenchCel Active X driver when a connection has been established (using the Initialize() method).
Parameters
None
Returns
1 if there is a connection and 0 if disconnected.
IsPlatePresent
LONG IsPlatePresent(SHORT sStack, [in, out] VARIANT_BOOL* pPresent
Description
Method to test whether a stack has a microplate and is loaded. If the stack is not loaded, the result returned through pPresent will not be meaningful. The stack number is 0-based. This method should be called after a successful connection.
Parameters
 
Argument Type
Argument Name
Range
Description
SHORT
sStack
0 to n-1, where n is the number of stacks
Which stack to check
VARIANT_BOOL*
pLoaded
Valid pointer to receive whether a microplate is present
On a successful call, the value pointed to by pPresent should indicate whether the stack is loaded and has a microplate available for downstacking
Returns
S_OK if successful, other value otherwise.
Visual C++ example
1Result = m_Benchcel.IsPlatePresent(1,&bPlatePresent);
Visual Basic example
1Result = BenchCel.IsPlatePresent(1,bPlatePresent)
IsStackLoaded
LONG IsStackLoaded(SHORT sStack, [in, out] VARIANT_BOOL* pLoaded
Description
Method to test whether a stack has been loaded. The stack number is 0-based. This method should be called after a successful connection.
Parameters
 
Argument Type
Argument Name
Range
Description
SHORT
sStack
0 to n-1, where n is the number of stacks
Which stack to check
VARIANT_BOOL*
pLoaded
Valid pointer to receive whether or not the stack is loaded
On a successful call, the value pointed to by pLoaded should indicate whether the stack is loaded or not
Returns
S_OK if successful; other value otherwise.
Visual C++ example
1Result = m_Benchcel.IsStackLoaded(1,&bStackLoaded);
Visual Basic example
1Result = BenchCel.IsStackLoaded(1,bStackLoaded)
LoadStack
LONG LoadStack(SHORT sStack)
Description
Method to release a stack. To downstack from or upstack to a stack, the stack must be loaded. A loaded stack is locked into the stacker head and cannot be freely taken from the device. The stack number is 0-based.
Parameters
 
Argument Type
Argument Name
Range
Description
SHORT
sStack
0 to n-1, where n is the number of stacks
The stack to be loaded
Returns
S_OK if successful; other value otherwise.
Visual C++ example
1Result = m_BenchCel.LoadStack(0);
Visual Basic example
1Result = BenchCel.LoadStack(0)
MoveToHomePosition
LONG MoveToHomePosition()
Description
Method to move the device to the origin. This method is not commonly used.
Parameters
None
Returns
S_OK if successful; other value otherwise.
Visual C++ example
1Result = BenchCel.MoveToHomePosition();
Visual Basic example
1Result = BenchCel.MoveToHomePosition()
OpenClamp
LONG OpenClamp(SHORT sStack)
Description
Method used to open the stacker grippers of a given stack.
Parameters
 
Argument Type
Argument Name
Range
Description
SHORT
sStack
0 – (number of Stacks – 1)
Specify which stack’s gripper to open
Returns
S_OK if successful; other value if there was an error.
Pause
LONG Pause()
Description
Disables the motors on the BenchCel device and pauses the motion.
See also the Unpause method.
IMPORTANT After the motors are disabled, the robot head and arms might have momentum and continue to move until they come to the end of the x‑axis, z‑axis, or theta‑axis, or until they bump into an obstacle.
Parameters
None
Returns
S_OK if successful; other value if there was an error.
PickAndPlace
LONG PickAndPlace(BSTR PickFrom, BSTR PlaceTo, VARIANT_BOOL bLidded, LONG nRetractionCode)
Description
Method to transfer a microplate. Stacker locations are called “Stacker 1”, “Stacker 2”, etc. Downstacking can be specified by using a stacker location for PickFrom and upstacking can be specified by using a stacker location for PlaceTo. bLidded indicates whether the robot should treat the microplate as if it has a lid. nRetractionCode should be 3 (reserved for future options).
Parameters
 
Argument Type
Argument Name
Range
Description
BSTR
PickFrom
Valid teachpoint name
Destination to pick from
BSTR
PlaceTo
Valid teachpoint name
Destination to place to
VARIANT_BOOL
bLidded
VARIANT_TRUE, VARIANT_FALSE
Whether the microplate is lidded
LONG
nRetractioCode
0–3
0– Do nothing
1– Retract normally
2– Not supported
3– Not supported
Returns
S_OK if success; other value otherwise.
Visual C++ example
1Result = m_BenchCel.PickAndPlace("Stacker 1", "PlateLoc", FALSE, 2)
Visual Basic example
1Result = BenchCel.PickAndPlace("Stacker 1", "PlateLoc", FALSE, 2)
ProtocolStart
LONG ProtocolStart()
Description
Method to be called at the beginning of a run. The device is not expected to move.
Parameters
None
Returns
S_OK on success; other value on failure.
Visual C++ example
1Result = m_BenchCel.ProtocolStart();
Visual Basic example
1Result = BenchCel.ProtocolStart()
ProtocolFinish
LONG ProtocolFinish()
Description
Method to be called at the end of a run. The device might home during this call.
Parameters
None
Returns
S_OK if success; other value otherwise.
Visual C++ example
1Result = m_BenchCel.ProtocolFinish();
Visual Basic example
1Result = BenchCel.ProtocolFinish()
ReleaseStack
LONG ReleaseStack(SHORT sStack)
Description
Method to release a stack. A released stack can be freely taken from the device for the loading or unloading of microplates. However, the BenchCel Microplate Handler cannot downstack from or upstack to a released stack. The stack number is 0‑based.
Note: This method can also be used to perform the close clamp function.
Parameters
 
Argument Type
Argument Name
Range
Description
SHORT
sStack
0 to n-1, where n is the number of stacks
The stack to be released
Returns
S_OK if successful, other value otherwise.
Visual C++ example
1Result = m_BenchCel.ReleaseStack(0);
Visual Basic example
1Result = BenchCel.ReleaseStack(0)
Relid
LONG Relid(BSTR RelidFrom, BSTR RelidTo, LONG nRetractionCode)
Description
Method used to put a lid on a microplate. You will need to specify where the lid is located and where the microplate is located. If the RelidFrom argument is blank, it is expected that the robot is holding the lid.
Parameters
 
Argument Type
Argument Name
Range
Description
BSTR
RelidFrom
Available teachpoints or blank string
Name of teachpoint where the lid is located
BSTR
RelidTo
Available teachpoints
Name of teachpoint where microplate that is getting the lid is located
LONG
nRetractionCode
0–3
How to position the robot arms after relidding the microplate, where
0– Do nothing
1– Retract normally
2– Not supported
3– Not supported
Returns
S_OK if successful; other value if there was an error.
Retry
LONG Retry()
Description
Method to retry an action after an error occurred. For example, if there is insufficient air pressure during a LoadStack operation, the application can call Retry after the air pressure has been increased.
Parameters
None
Returns
S_OK if success; other value otherwise.
Visual C++ example
m_BenchCel.Retry();
Visual Basic example
BenchCel.Retry
SetLabware
LONG SetLabware(BSTR bstrLabware)
Description
Method to set the labware to use. The selection will be in effect for all operations until a different labware is set. If diagnostics are shown and the user selects a different labware, the original labware will be restored when the diagnostics window is closed. This method should not be called when any movement is in progress.
Parameters
 
Argument Type
Argument Name
Range
Description
BSTR
bstrLabware
Valid labware name
Labware to be used for subsequent operations
Returns
S_OK if successful; other value if there was an error.
Visual C++ example
1Result = m_BenchCel.SetLabware("MyPlateType");
Visual Basic example
1Result = BenchCel.SetLabware("MyPlateType")
ShowDiagsDialog
LONG ShowDiagsDialog(BOOL bModal, SHORT iSecurityLevel)
Description
Method to show the graphical diagnostics menu that allows the user to troubleshoot and correct problems. This method can be called before Initialize to create a profile.
Parameters
 
Argument Type
Argument Name
Range
Description
BOOL
bModal
TRUE,FALSE
Whether the diagnostics should be shown modally
SHORT
iSecurityLevel
0-3
The security level that the user has to operate the diagnostics
0 = Administrator
1 = Technician
2 = Operator
3 = Guest
–1 - No access
Returns
LONG —no meaning.
Visual C++ example
m_BenchCel.ShowDiagsDialog(TRUE,0);
Visual Basic example
BenchCel.ShowDiagsDialog 1, 0
ShowLabwareEditor
LONG ShowLabwareEditor(BOOL bModal, BSTR bstrLabware)
Description
Method to display the labware editor graphical user interface. Through this interface dialog, the user can specify labware parameters that will be used by the device to handle the microplates. Parameters such as microplate height and notch information will be associated with a labware name, which can be used by SetLabware to indicate to the device how to handle the next microplate.
Parameters
 
Argument Type
Argument Name
Range
Description
BOOL
bModal
TRUE, FALSE
Whether to show the editor modally or not
BSTR
bstrLabware
Valid labware name
The labware to be selected when the editor is displayed
Returns
S_OK if successful; other value otherwise.
Visual C++ example
m_BenchCel.ShowLabwareEditor(1,"MyPlateType");
Visual Basic example
BenchCel.ShowLabwareEditor 1,"MyPlateType"
Unpause
LONG Unpause()
Description
Re-enables the motors on the BenchCel Microplate Handler. The BenchCel Microplate Handler will resume any remaining movements that were in process before the call to pause the device.
See also the Pause method.
Parameters
None
Return
S_OK if successful; other value if there was an error.
Related topics
 
For information about...
See...
BenchCel ActiveX properties
Properties
BenchCel ActiveX events
Events
Overview of the ActiveX controls
About ActiveX controls
Reporting problems
Reporting problems