Main Page | Features | Central Services | csv-Files | Types | Transfer | Access | API-C | API-VB/ActiveX | API-Java | Examples | Downloads

CACOPCtrl Class Reference

List of all members.

Detailed Description

Implementation of the CACOPCtrl ActiveX Control class.

Protected Member Functions

afx_msg BOOL GetIsZoomed ()
 returns the zoomed state of the ACOP display.
afx_msg long Execute (const VARIANT FAR &Data, const VARIANT FAR &ArraySize, const VARIANT FAR &DataType, const VARIANT FAR &DataEx, const VARIANT FAR &ArraySizeEx, const VARIANT FAR &DataTypeEx)
 Execute a synchronous link with the given calling parameters.
afx_msg long Draw (const VARIANT FAR &Yarray, const VARIANT FAR &Xarray, const VARIANT FAR &disable, const VARIANT FAR &Xlabel, const VARIANT FAR &ArraySize, const VARIANT FAR &DataType, const VARIANT FAR &MaxNumber)
 Principal method for displaying data.
afx_msg long PrintText (LPCTSTR Text, const VARIANT FAR &Xposition, const VARIANT FAR &Yposition, const VARIANT FAR &Moveable)
 Prints text strings on the ACOP display.
afx_msg void ClearScreen (const VARIANT FAR &hDisplay, const VARIANT FAR &KeepDepth)
 Clears the data display of the input display handle.
afx_msg void AutoScale (const VARIANT FAR &XMax, const VARIANT FAR &XMin, const VARIANT FAR &YMax, const VARIANT FAR &YMin)
 Sets the maximum and minimum scale coordinates to accomodate the currently displayed data.
afx_msg BSTR CTime (const VARIANT FAR &TimeStamp)
 converts the UTC timestamp given into a human readable string.
afx_msg long OpenLink (const VARIANT FAR &Data, const VARIANT FAR &ArraySize, const VARIANT FAR &DataType, const VARIANT FAR &DataEx, const VARIANT FAR &ArraySizeEx, const VARIANT FAR &DataTypeEx)
 Establishes an asynchronous link with the given calling parameters.
afx_msg long AttachLink (const VARIANT FAR &Data, const VARIANT FAR &ArraySize, const VARIANT FAR &DataType, const VARIANT FAR &DataEx, const VARIANT FAR &ArraySizeEx, const VARIANT FAR &DataTypeEx)
 Establishes an asynchronous link with the given calling parameters.
afx_msg long CloseLink (const VARIANT FAR &hLink)
 Closes (i.e. cancels) the link given, or all links if no link is specified.
afx_msg long GetData (const VARIANT FAR &Data, const VARIANT FAR &DataEx, const VARIANT FAR &hLink)
 Retrieves data into the calling process.
afx_msg BOOL Marker (const VARIANT FAR &MarkerOn, const VARIANT FAR &hDisplay)
 Turns Display markers on or off and returns the current marker state for the display handle specified.
afx_msg void RecallScreen (const VARIANT FAR &hDisplay)
 Recovers previously cleared ACOP screens.
afx_msg void ClearText (const VARIANT FAR &hText)
 Clears the displayed text in the given text window.
afx_msg long PrintScreen (const VARIANT FAR &Position)
 Sends the ACOP control display to the default printer.
afx_msg long LockScreen (const VARIANT FAR &LockOn, const VARIANT FAR &hDisplay)
 Locks the specified display in the ACOP control.
afx_msg long AppendScreen (const VARIANT FAR &Yarray, long hDisplay, const VARIANT FAR &Npoints, const VARIANT FAR &StartIndex, const VARIANT FAR &Xarray)
 Appends data to an already drawn data array.
afx_msg long GetDataSize (const VARIANT FAR &DataSize, const VARIANT FAR &DataSizeEx, const VARIANT FAR &hLink)
 Retrieves the returned size of data set.
afx_msg double GetDataTimestamp ()
 Retrieves the data timestamp of the most recent completed link.
afx_msg void SetNotificationTolerance (BOOL notifyOnChange, const VARIANT FAR &toleranceAbsolute, const VARIANT FAR &tolerancePercent)
 Sets a 'notify on change' flag and optionally provides a tolerance against which a data change is measured.
afx_msg long SetNotificationId (long LinkHandle, long LinkId)
 Sets the notification identifier.
afx_msg long GetLinkStatus (long LinkId)
 Retrieves the current link status for the link handle given.

Member Function Documentation

BOOL GetIsZoomed (  )  [protected]

returns the zoomed state of the ACOP display.

Visual Basic prototype: GetIsZoomed()

Returns:
TRUE if the ACOP control is in a zoomed state, otherwise returns FALSE.

long Execute ( const VARIANT FAR &  Data,
const VARIANT FAR &  ArraySize,
const VARIANT FAR &  DataType,
const VARIANT FAR &  DataEx,
const VARIANT FAR &  ArraySizeEx,
const VARIANT FAR &  DataTypeEx 
) [protected]

Execute a synchronous link with the given calling parameters.

Visual Basic prototype: Execute([Data] [,ArraySize] [,DataType] [,DataEx] [,ArraySizeEx] [,DataTypeEx]) as long

Synchronous data exchange. Calls to Execute() attempt to establish and execute the requested data link with the given calling parameters and do not return until the call has completed, either due to successful data return or an error condition or timeout has occurred.

Parameters:
Data (optional) is the data set to receive the output data upon successful data acquisition.
ArraySize (optional) gives the array size of the reqested output data set. If not specified, the array size of the variable passed as ‘Data’ will be used.
DataType (optional) gives the data type (as a string) of the requested output data set. If not specified, the data type of the variable passed as ‘Data’ will be used. For the elementary data types (byte, short int, long int, float, double) it is not necessary to specify this parameter. In fact it is safer not to pass it, since acop will then examine the ‘Data’ variable itself and guarantee not to overwrite arrays etc. However, for non-elementary or user-defined data types, it is necessary to pass the requested format type in string representation, for instance "FLTINT" for type CF_FLTINT. In such cases, the variable passed as ‘Data’ must be the very first instance of a "FLTINT" structure.
DataEx (optional) is the 'extended' data set to be sent as input data to the front end server.
ArraySizeEx (optional) refers to 'DataEx' and is analogous to ‘ArraySize’.
DataTypeEx (optional) refers to 'DataEx' and is analogous to ‘DataType’.
Returns:
0 upon success, or the error code indicating the error condition. The Status property can be examined to see the cause of the error in plain text.
Note:
Execute() is synchronous, which means that execution within the calling process stops until the call completes. This could amount to blocking the process for the duration of the timeout specified (set by the AccessRate parameter). An asychronous alternative is to use AttachLink() with "READ" or "WRITE" access, in which case the results of the operation are returned when the Receive Event fires.
Example: 

Dim mode As short
Dim idMode As Long

Private Sub SetMode(ByVal targetMode As Short)
  Dim rc As Long

  ACOP1.DeviceContext = "HERA"
  ACOP1.DeviceGroup = "HEPBPM"
  ACOP1.DeviceName = "WL197 MX"
  ACOP1.DeviceProperty = "ONLINE"
  ACOP1.AccessMode = "READ|WRITE"
  ACOP1.AccessRate = 1000
  ACOP1.AccessProtocol = "TINE"

  rc = ACOP1.Execute(mode, , , targetMode)

  If rc <> 0 Then MsgBox "SetMode failed : " + ACOP1.Status

End Sub

See also:
OpenLink(), AttachLink(), GetData()

long Draw ( const VARIANT FAR &  Yarray,
const VARIANT FAR &  Xarray,
const VARIANT FAR &  disable,
const VARIANT FAR &  Xlabel,
const VARIANT FAR &  ArraySize,
const VARIANT FAR &  DataType,
const VARIANT FAR &  MaxNumber 
) [protected]

Principal method for displaying data.

Visual Basic prototype: Draw(Yarray [,Xarray] [,Disabled] [,Xlabel] [,ArraySize] [,DataType]) as long

The principal drawing method is Draw(), which takes at least one parameter, namely Yarray, which is the first argument in the parameter list. If only Yarray is passed, then a trace is drawn by assuming an evenly spaced X-axis array beginning at 0 and ending at the number of points minus 1. In many cases this is precisely what is desired, hence the first parameter is the Yarray and not the Xarray (which is optional). This may at first seem counter-intuitive, but spares the programmer from remembering to include a comma in the method call in order to skip an optional Xarray.

Draw() can be called repeated without clearing via the ClearScreen() method. If so, the Draw() buffers are stored (in a ring buffer) to the depth defined by the ScreenDepth setting. Each successive call to Draw() returns a new display handle if successful. If the ReuseScreen setting is FALSE (default) then a call to Draw() will fail if the number of uncleared Draw() buffers is equal to the ScreenDepth.

The appearance of the drawn display is determined by the ForeColor, DrawStyle, and DrawWidth properties. The type of display (histogram versus poly-line for instance) is determined by the DisplayMode property.

Parameters:
Yarray cast to VARIANT, by reference. The trace array to be drawn. Any OLE basic type may be passed, and will be cast into a VARIANT reference. A VARIANT itself may not be passed. Typically, an array of doubles, singles, longs, or shorts is passed here. Internally, all data arrays are converted and stored as doubles. If user-defined data, or double arrays are passed, then you must pass a reference to the first (OLE basic type) element of the user type, and pass the type information in the DataType parameter, and the size information in ArraySize.
Xarray cast to VARIANT, by reference [Optional]. An accompanying horizontal position array to associate with the Yarray passed. Any OLE basic type may be passed, and will be cast into a VARIANT reference. A VARIANT itself may not be passed. Typically, an array of doubles, singles, longs, or shorts is passed here. Internally, all data arrays are converted and stored as doubles. If user-defined data, or double arrays are passed, then you must pass a reference to the first (OLE basic type) element of the user type, and pass the type information in the DataType parameter, and the size information in ArraySize. Furthermore, the DataType information must correspond to that for the Yarray, in that the element size must be the same. If Xarray is passed, it must have the same number of elements as the Yarray.
Disabled cast to VARIANT, by reference [Optional]. Can be used to selectively draw certain indices or not (for instance if an accompanying status array indicates that a certain set of monitors is bad). A single value passed in this position will enable/disable all array elements.
Xlabel cast to VARIANT, by reference [Optional]. A string array corresponding to labels to be assigned to the X-axis tick marks. If present, the string labels contained in the given array are drawn on the x-axis instead of the corresponding numerical X-value. This is very useful when for instance histograms of monitor readings are being displayed.
ArraySize cast to VARIANT, by reference [Optional]. Can specify the array size of the Yarray, Xarray passed, regardless of the actual dimensions of the objects passed for these variables. If DataType is not specified, and ArraySize is not equal or less than the actual dimensions, then a return code of -1 is returned instead of a display index.
DataType cast to VARIANT, by reference [Optional]. DataType and ArraySize correspond to the arguments of the same names used in the data access methods Execute(), AttachLink() and OpenLink(). Namely they can be used to override the array dimension of the passed Yarray and/or specify a user-defined type or double array (see above). In this case, drawing an array of user-defined types will make the same query to ACOP.DLL to determine the structure size, and use this value as the offset between elements.
MaxNumber cast to VARIANT, by reference [Optional]. This parameter can be used to fix the drawn data array size to the value given, regardless of the array sizes of the any other parameters. It is similar in function to the ArraySize parameter, but is generally used to reserve a draw array buffer with a specific size (e.g. in trend charts of a given depth).
Returns:
hDisplay upon success (a handle to a valid ACOP display), which can be used in various display methods. Otherwise a value of -1 is returned.

long PrintText ( LPCTSTR  Text,
const VARIANT FAR &  Xposition,
const VARIANT FAR &  Yposition,
const VARIANT FAR &  Moveable 
) [protected]

Prints text strings on the ACOP display.

Visual Basic prototype: PrintText(Text [,Xposition] [,Yposition] [,Locater]) As Long

The PrintText() method can be used to print labels or text directly on the display. The Text argument must be present. The optional Xposition and Yposition can be used to position the text. The optional parameter Locator allows backward compatibility with ACOP 1.1. Its purpose and functionality is superceded by the PrintTextLocation and PrintTextStickyAttribute properties. PrintText() returns a long handle to the text printed. This handle can be stored and used in subsequent calls to RefreshText(), RecallText() or ClearText(). The number of allowed text displays is given by the TextDepth property (default =20).

Parameters:
Text The text to be printed.
Xposition Horizontal position in user coordinates of the printed text. [cast to VARIANT. Optional]. If omitted, Xposition = 0.
Yposition Vertical position in user coordinates of the printed text. [cast to VARIANT. Optional]. If omitted, Yposition = 0.
Locater [Deprecated]. Determines the relative printed text location and sticky attributes via bit-wise input. Use the PrintTextLocation and PrintTextStickyAttribute properties instead.
Returns:
A positive handle to a printed text block upon success, otherwise -1.

void ClearScreen ( const VARIANT FAR &  hDisplay,
const VARIANT FAR &  KeepDepth 
) [protected]

Clears the data display of the input display handle.

Visual Basic prototype: ClearScreen([hDisplay] [,KeepDepth])

ClearScreen() is used to clear the display screen as well as all display buffers. Typically one calls ClearScreen before calling Draw(), the principal drawing method. Many displays can be drawn on the same ACOP control, up to the number allowed as given by the ScreenDepth parameter. If the ReuseScreen property is set to FALSE, then the ClearScreen() method must be called before any new displays may be drawn with the Draw() method. ClearScreen() erases the contents of the designated display (all if none given).

Parameters:
hDisplay cast to VARIANT [Optional]. The display index of the display to be cleared. If omitted, all displays are cleared.
KeepDepth cast to VARIANT [Optional]. If present, a call to ClearScreen will clear all except for the last KeepDepth number of arrays. These kept arrays will be redrawn according to the KeepColor, KeepWidth, and KeepStyle pen properties. This is useful when emulating an oscilloscope-like trace with persistence.
Returns:
0 upon success, else -1 (if for instance a non-valid DisplayNumber was passed).

void AutoScale ( const VARIANT FAR &  XMax,
const VARIANT FAR &  XMin,
const VARIANT FAR &  YMax,
const VARIANT FAR &  YMin 
) [protected]

Sets the maximum and minimum scale coordinates to accomodate the currently displayed data.

Visual Basic prototype: AutoScale([XMax] [, Xmin] [,Ymax] [,Ymin])

The AutoScale() method can be called at anytime to adjust the X and Y axis maximum and minimum settings (according to the optional boolean arguments). AutoScale applies to all drawn displays and can only work if something has been drawn.

Parameters:
XMax cast to VARIANT [Optional]. Evaluates to Boolean. If True, adjusts the XMax property of the control to accommodate all drawn data. If omitted, False is assumed, and the XMax value is left unaltered.
XMin cast to VARIANT [Optional]. Evaluates to Boolean. If True, adjusts the XMin property of the control to accommodate all drawn data. If omitted, False is assumed, and the XMin value is left unaltered.
YMax cast to VARIANT [Optional]. Evaluates to Boolean. If True, adjusts the YMax property of the control to accommodate all drawn data. If omitted, False is assumed, and the YMax value is left unaltered.
YMin cast to VARIANT [Optional]. Evaluates to Boolean. If True, adjusts the YMin property of the control to accommodate all drawn data. If omitted, False is assumed, and the YMin value is left unaltered.

BSTR CTime ( const VARIANT FAR &  TimeStamp  )  [protected]

converts the UTC timestamp given into a human readable string.

Visual Basic prototype: CTime([TimeStamp])

Parameters:
TimeStamp [optional] is the UTC timestamp for which the time string is to be calculated. If not given, the current system time is used.
Returns:
the time string of the timestamp given

long OpenLink ( const VARIANT FAR &  Data,
const VARIANT FAR &  ArraySize,
const VARIANT FAR &  DataType,
const VARIANT FAR &  DataEx,
const VARIANT FAR &  ArraySizeEx,
const VARIANT FAR &  DataTypeEx 
) [protected]

Establishes an asynchronous link with the given calling parameters.

Visual Basic prototype: OpenLink([Data] [,ArraySize] [,DataType] [,DataEx] [,ArraySizeEx] [,DataTypeEx]) as long

Asynchronous data exchange. Calls in the AttachLink() family attempt to establish the requested data link with the given calling parameters and complete immediately. If the address of the requested server can be resolved and the calling parameters are otherwise okay, the call will complete successfully and return a valid (positive) link handle. This does not mean that the requested server will respond to the request. The data and status information from the server will be returned asynchronously inside the callback routine passed in the call. A client can establish an asynchronous link by calling AttachLink() or OpenLink(). OpenLink() differs from AttachLink() in that with OpenLink() input and output data sets are not bound to the data set parameters passed in the call. Thus, upon Receive event notification, one must retrieve the output data set into the calling process. This is sometimes the preferred modus operandi. For instance if a common data buffer is used for several active links, it is not 'safe' to expect the data set to retain its integrity following a Receive Event. In such cases, the implicit 'double buffering' of OpenLink is preferrable.

Also note that with OpenLink() the Data object can be on the temporary stack at the time of the call, since the internal data object ACOP uses is in this case not 'Attached' to the data object used in the calling routine. This is not true with AttachLink().

Parameters:
Data (optional) is the data set to receive the output data upon successful data acquisition. In OpenLink() this parameter is used only to prototype the data set. The actual returned data needs to be retrieved via a call to GetData() using a similar data set.
ArraySize (optional) gives the array size of the reqested output data set. If not specified, the array size of the variable passed as ‘Data’ will be used.
DataType (optional) gives the data type (as a string) of the requested output data set. If not specified, the data type of the variable passed as ‘Data’ will be used. For the elementary data types (byte, short int, long int, float, double) it is not necessary to specify this parameter. In fact it is safer not to pass it, since acop will then examine the ‘Data’ variable itself and guarantee not to overwrite arrays etc. However, for non-elementary or user-defined data types, it is necessary to pass the requested format type in string representation, for instance "FLTINT" for type CF_FLTINT. In such cases, the variable passed as ‘Data’ must be the very first instance of a "FLTINT" structure.
DataEx (optional) is the 'extended' data set to be sent as input data to the front end server.
ArraySizeEx (optional) refers to 'DataEx' and is analogous to ‘ArraySize’.
DataTypeEx (optional) refers to 'DataEx' and is analogous to ‘DataType’.
Returns:
A positive link handle upon success, or -1 upon failure. The call returns immediately, so the return value should be checked and if equal to -1, the Status property can be examined to see the cause of the error, which in this case will indicate that the link cannot be established due to an internal inconsistency. Upon success, the link handle returned can be stored to be used as input to other methods. This is particularly important for the case where more than one data links are bound to a given component.
Note:
Using OpenLink() necessitates calling the GetData() method inside the Receive Event in order to retrieve the incoming data into the calling process. Consider the simple case:
Dim Xorbit(140) As Single
Dim Yorbit(140) As Single
Dim idXorbit As Long
Dim idYorbit As Long

Private Sub Form_Load()
  Dim orbit(140) As Single

  ACOP1.DeviceContext = "HERA"
  ACOP1.DeviceGroup = "HEPBPM"
  ACOP1.DeviceName = "WL197 MX"
  ACOP1.DeviceProperty = "ORBIT.X"
  ACOP1.AccessMode = "POLL"
  ACOP1.AccessRate = 1000
  ACOP1.AccessProtocol = "TINE"
  ACOP1.Grouped = True

  idXorbit = ACOP1.OpenLink(orbit)

  ACOP1.DeviceName = "WL164 MY"
  ACOP1.DeviceProperty = "ORBIT.Y"

  idYorbit = ACOP1.OpenLink(orbit)

End Sub
Private Sub ACOP1_Receive(ByVal LinkIndex As Long, ByVal StatusCode As Long)
  If StatusCode <> 0 Then
    ErrorLabel.Caption = "Orbit Link : " + ACOP1.Status
    Exit Sub
  End If

  ACOP1.GetData Xorbit,,idXorbit
  ACOP1.GetData Yorbit,,idYorbit

  ACOP1.ClearScreen
  ACOP1.ForeColor = vbBlue
  ACOP1.Draw Xorbit
  ACOP1.ForeColor = vbRed
  ACOP1.Draw Yorbit

End Sub

The same discussion presented in AttachLink() as to the calling scenarios applies with OpenLink() as well.

See also:
AttachLink(), Execute(), GetData()

long AttachLink ( const VARIANT FAR &  Data,
const VARIANT FAR &  ArraySize,
const VARIANT FAR &  DataType,
const VARIANT FAR &  DataEx,
const VARIANT FAR &  ArraySizeEx,
const VARIANT FAR &  DataTypeEx 
) [protected]

Establishes an asynchronous link with the given calling parameters.

Visual Basic prototype: AttachLink([Data] [,ArraySize] [,DataType] [,DataEx] [,ArraySizeEx] [,DataTypeEx]) as long

Asynchronous data exchange. Calls in the AttachLink() family attempt to establish the requested data link with the given calling parameters and complete immediately. If the address of the requested server can be resolved and the calling parameters are otherwise okay, the call will complete successfully and return a valid (positive) link handle. This does not mean that the requested server will respond to the request. The data and status information from the server will be returned asynchronously inside the callback routine passed in the call. A client can establish an asynchronous link by calling AttachLink() or OpenLink(). AttachLink() differs from OpenLink() in that with AttachLink() input and output data sets are bound to the data set parameters passed in the call. Thus, upon Receive event notification, one knows that the output data set already contains the most recent output data from the remote server.

Parameters:
Data (optional) is the data set to receive the output data upon successful data acquisition.
ArraySize (optional) gives the array size of the reqested output data set. If not specified, the array size of the variable passed as ‘Data’ will be used.
DataType (optional) gives the data type (as a string) of the requested output data set. If not specified, the data type of the variable passed as ‘Data’ will be used. For the elementary data types (byte, short int, long int, float, double) it is not necessary to specify this parameter. In fact it is safer not to pass it, since acop will then examine the ‘Data’ variable itself and guarantee not to overwrite arrays etc. However, for non-elementary or user-defined data types, it is necessary to pass the requested format type in string representation, for instance "FLTINT" for type CF_FLTINT. In such cases, the variable passed as ‘Data’ must be the very first instance of a "FLTINT" structure.
DataEx (optional) is the 'extended' data set to be sent as input data to the front end server.
ArraySizeEx (optional) refers to 'DataEx' and is analogous to ‘ArraySize’.
DataTypeEx (optional) refers to 'DataEx' and is analogous to ‘DataType’.
Returns:
A positive link handle upon success, or -1 upon failure. The call returns immediately, so the return value should be checked and if equal to -1, the Status property can be examined to see the cause of the error, which in this case will indicate that the link cannot be established due to an internal inconsistency. Upon success, the link handle returned can be stored to be used as input to other methods. This is particularly important for the case where more than one data links are bound to a given component.
Note:
Using AttachLink() can be very easy. Consider the simple case where the horizontal and vertical orbits can be accessed as simple arrays of floats. In Visual Basic a float is a 'Single' and we could have the following code as an example:
Dim Xorbit(140) As Single
Dim Yorbit(140) As Single
Dim idXorbit As Long
Dim idYorbit As Long

Private Sub Form_Load()

  ACOP1.DeviceContext = "HERA"
  ACOP1.DeviceGroup = "HEPBPM"
  ACOP1.DeviceName = "WL197 MX"
  ACOP1.DeviceProperty = "ORBIT.X"
  ACOP1.AccessMode = "POLL"
  ACOP1.AccessRate = 1000
  ACOP1.AccessProtocol = "TINE"

  idXorbit = ACOP1.AttachLink(Xorbit)

  ACOP1.DeviceName = "WL164 MY"
  ACOP1.DeviceProperty = "ORBIT.Y"

  idYorbit = ACOP1.AttachLink(Yorbit)

End Sub

This is practically equivalent to suppling the optional ArraySize and DataType parameters as follows:

Dim Xorbit(140) As Single
Dim Yorbit(140) As Single
Dim idXorbit As Long
Dim idYorbit As Long

Private Sub Form_Load()

  ACOP1.DeviceContext = "HERA"
  ACOP1.DeviceGroup = "HEPBPM"
  ACOP1.DeviceName = "WL197 MX"
  ACOP1.DeviceProperty = "ORBIT.X"
  ACOP1.AccessMode = "POLL"
  ACOP1.AccessRate = 1000
  ACOP1.AccessProtocol = "TINE"

  idXorbit = ACOP1.AttachLink(Xorbit, 141, "FLOAT")

  ACOP1.DeviceName = "WL164 MY"
  ACOP1.DeviceProperty = "ORBIT.Y"

  idYorbit = ACOP1.AttachLink(Yorbit, 141, "FLOAT")

End Sub

If the same orbits are to be obtained as arrays of a complex format type such as the TINE doublet CF_FLTINT, where a position (float) and a status (int) are returned for each element of the orbit, then you need to supply the starting entry variable of the data object which to receive the data, as shown below:

' This should either be declared as Private Const or declared in a .bas Module:
Type FLTINT
  fval As Single
  ival As Long
End Type

Dim Xorbit(140) As FLTINT
Dim Yorbit(140) As FLTINT
Dim idXorbit As Long
Dim idYorbit As Long

Private Sub Form_Load()

  ACOP1.DeviceContext = "HERA"
  ACOP1.DeviceGroup = "HEPBPM"
  ACOP1.DeviceName = "WL197 MX"
  ACOP1.DeviceProperty = "ORBIT.X"
  ACOP1.AccessMode = "POLL"
  ACOP1.AccessRate = 1000
  ACOP1.AccessProtocol = "TINE"

  idXorbit = ACOP1.AttachLink(Xorbit(0).fval, 141, "FLTINT")

  ACOP1.DeviceName = "WL164 MY"
  ACOP1.DeviceProperty = "ORBIT.Y"

  idYorbit = ACOP1.AttachLink(Yorbit(0).fval, 141, "FLTINT")

End Sub

In all of the cases above, note that the data array to receive the output data is allocated globally (i.e. not on the stack!). This is because, AttachLink() explicitly copies the returned data into the data object you specify. If this is not wished, then you should make use of the OpenLink() method, whose behavior is the same as AttachLink() with the exception that it does not bind the returned data to the data object supplied in the initial call. Instead the user is required to call the GetData() method to retrieve the returned data into the application's address space.

Finally, as a case in point, if you wanted to initiate a WRITE command, for instance turning a monitor on or off line, and do this asynchronously, i.e. the results of the call come via the ACOP event callback, then you might do so as follows:

Dim mode As short
Dim idMode As Long

Private Sub SetMode(ByVal targetMode As Short)

  ACOP1.DeviceContext = "HERA"
  ACOP1.DeviceGroup = "HEPBPM"
  ACOP1.DeviceName = "WL197 MX"
  ACOP1.DeviceProperty = "ONLINE"
  ACOP1.AccessMode = "READ|WRITE"
  ACOP1.AccessRate = 1000
  ACOP1.AccessProtocol = "TINE"

  idMode = ACOP1.AttachLink(mode, , , targetMode)

End Sub

Note that as written above, the command to set the ONLINE property will issue a WRITE + READ, that is set the value and read the value back after the set as an atomic call. The value sent as input to the server can be global or on the local heap, however if AttachLink is used, the output variable must be global.

See also:
OpenLink(), Execute(), GetData()

long CloseLink ( const VARIANT FAR &  hLink  )  [protected]

Closes (i.e. cancels) the link given, or all links if no link is specified.

Visual Basic prototype: CloseLink([hLink]) as long

Parameters:
hLink (optional) specifies the link handle to be closed. If not specified, all associated links will be closed.
See also:
OpenLink(), AttachLink()

long GetData ( const VARIANT FAR &  Data,
const VARIANT FAR &  DataEx,
const VARIANT FAR &  hLink 
) [protected]

Retrieves data into the calling process.

Visual Basic prototype: GetData([Data] [,DataEx] [,hLink]) as long

Used in conjunction with OpenLink() in asynchronous data exchange. A client can establish an asynchronous link by calling AttachLink() or OpenLink(). OpenLink() differs from AttachLink() in that with OpenLink() input and output data sets are not bound to the data set parameters passed in the call. Thus, upon Receive event notification, one must retrieve the output data set into the calling process. This is sometimes the preferred modus operandi. For instance if a common data buffer is used for several active links, it is not 'safe' to expect the data set to retain its integrity following a Receive Event. In such cases, the implicit 'double buffering' of OpenLink is preferrable.

GetData() can also be useful when data links are started with AttachLink() when 'grouped' links are in force (Grouped = True). When the group has an error condition, one way of ascertaining what the error condition is, is to call GetData for the link in question and examine the error code returned. Note in cases of 'grouped links', the TINE 'USE_ON_ERROR' modifier is extemely useful for identifying the 'faulty' links. Without it, you would have to call GetData() for all elements of the group when an error condition arises.

Parameters:
Data (optional) is the data set to receive the output data upon successful notifiation of data acquisition (StatusCode = 0).
DataEx (optional) is the 'extended' data set and has no meaning in a call to GetData() using the TINE protocol.
hLink (optional) is the link handle assigned with a successful call to OpenLink() or AttachLink(). It can only be omitted when the ACOP component in question has only one active link bound to it.
Returns:
The link status for the link in question, i.e. 0 upon success, otherwise the corresponding error code from the data access sublayer.
Dim Xorbit(140) As Single
Dim Yorbit(140) As Single
Dim idXorbit As Long
Dim idYorbit As Long

Private Sub Form_Load()
  Dim orbit(140) As Single

  ACOP1.DeviceContext = "HERA"
  ACOP1.DeviceGroup = "HEPBPM"
  ACOP1.DeviceName = "WL197 MX"
  ACOP1.DeviceProperty = "ORBIT.X"
  ACOP1.AccessMode = "POLL"
  ACOP1.AccessRate = 1000
  ACOP1.AccessProtocol = "TINE"
  ACOP1.Grouped = True

  idXorbit = ACOP1.OpenLink(orbit)

  ACOP1.DeviceName = "WL164 MY"
  ACOP1.DeviceProperty = "ORBIT.Y"

  idYorbit = ACOP1.OpenLink(orbit)

End Sub
Private Sub ACOP1_Receive(ByVal LinkIndex As Long, ByVal StatusCode As Long)
  If StatusCode <> 0 Then
    ErrorLabel.Caption = "Orbit Link : " + ACOP1.Status
    Exit Sub
  End If

  ACOP1.GetData Xorbit,,idXorbit
  ACOP1.GetData Yorbit,,idYorbit

  ACOP1.ClearScreen
  ACOP1.ForeColor = vbBlue
  ACOP1.Draw Xorbit
  ACOP1.ForeColor = vbRed
  ACOP1.Draw Yorbit

End Sub

See also:
AttachLink(), OpenLink()

BOOL Marker ( const VARIANT FAR &  MarkerOn,
const VARIANT FAR &  hDisplay 
) [protected]

Turns Display markers on or off and returns the current marker state for the display handle specified.

Visual Basic prototype: Marker([MarkerOn], [hDisplay]) As Boolean

If markers are desired around the displayed data points, the appearance of the markers can be set with the marker properties: MarkerMode, MarkerStyle, MarkerWidth, MarkerXExtent, and MarkerYExtent. The markers themselves are made visible or not via the Marker() method.

Parameters:
MarkerOn cast to VARIANT [Optional]. Is interpreted as Boolean, where a value of ‘0’ turns the marker display off, and any non-zero value turns the marker display on. If MarkerOn is not passed, then the current marker state is left unchanged (for instance, a call to Marker() is made to check whether the marker display is on or not).
hDisplay cast to VARIANT, by reference [Optional]. Gives the handle to the display for which markers are to be turned on. If omitted, hDisplay assumes the default value of -1, which will then refer to all plotted displays.
Returns:
Boolean value indicating whether Marker display is on or off for the display index given.

void RecallScreen ( const VARIANT FAR &  hDisplay  )  [protected]

Recovers previously cleared ACOP screens.

Visual Basic prototype: RecallScreen(hDisplay])

RecallScreen() can be used to recover the last cleared screen displays. If called with no parameter, it recalls all displays drawn since the last ClearScreen(). If called with the DisplayNumber parameter, it recalls only the indicated plot. .

Parameters:
hDisplay gives the display index of the display to be recalled. [cast to VARIANT. Optional]. If omitted, all displays are redrawn since the last ClearScreen().

void ClearText ( const VARIANT FAR &  hText  )  [protected]

Clears the displayed text in the given text window.

Visual Basic prototype: ClearText([hText])

The primary method for printing text in ACOP is the PrintText() method. Printed text can at any time be cleared via the ClearText() method, which clears all text display if the optional handle hText is not passed. Otherwise it clears the specified text rectangle. The usual method of updating text on a display is to first call the ClearText() method in order to remove all text content and then call the PrintText() method. Alternatively, on can set the ReuseText Property to TRUE and the TextDepth property to 1, which would have the effect of clearing the printed text prior to the next call to PrintText().

Parameters:
hText the handle to the text rectangle to be cleared. [cast to VARIANT. Optional]. If omitted, all text rectangles are cleared.
Returns:
0 upon success, otherwise -1 (if the handle is invalid).

long PrintScreen ( const VARIANT FAR &  Position  )  [protected]

Sends the ACOP control display to the default printer.

Visual Basic prototype: PrintScreen([Position])

The PrintScreen() method can be used to send just the ACOP control display area to the default printer. The method takes one optional parameter, which governs the position of the plot on the printed page. "0" (default) positions the display at the top of the page, "1" in the middle, otherwise the plot is positioned at the bottom. The display area is always scaled to fill the largest area.

Parameters:
Position sets position of the ACOP display on the printed page. [cast to VARIANT. Optional]. If omitted, Position defaults to 0, which positions the output at the top of the printed page. Position = 1 prints to the middle. Otherwise, the ACOP display is printed at the bottom of the page.
Returns:
0 upon success, otherwise -1.

long LockScreen ( const VARIANT FAR &  LockOn,
const VARIANT FAR &  hDisplay 
) [protected]

Locks the specified display in the ACOP control.

Visual Basic prototype: LockScreen([LockOn] [,hDisplay])

The principal drawing method is Draw(). It is occasionally desirable to fix one or more displays to the ACOP control and be able to clear all others with a simple call to the ClearScreen() method. The way to achieve this is to call the LockScreen() method for all displays which are to remained fixed. Locked displays also maintain their appearance, determined by the ForeColor, DrawStyle, and DrawWidth properties, and mode, determined by the DisplayMode property.

Parameters:
LockOn If set to TRUE, locks a display and all its display information in the ACOP control. [cast to VARIANT. Optional]. Evaluates to Boolean. Subsequent calls to ClearScreen() have no effect on the locked display. If omitted has no effect.
hDisplay gives the display handle of the display to be locked or unlocked. [cast to VARIANT. Optional]. If omitted, all drawn displays are either locked or unlocked.
Returns:
the number of locked displays if the hDisplay argument is omitted, otherwise returns 0 (unlocked) or 1 (locked), or -1 (error).

long AppendScreen ( const VARIANT FAR &  Yarray,
long  hDisplay,
const VARIANT FAR &  Npoints,
const VARIANT FAR &  StartIndex,
const VARIANT FAR &  Xarray 
) [protected]

Appends data to an already drawn data array.

Visual Basic prototype: AppendScreen(Yarray, hDisplay [,Npoints] [,StartIndex] [,Xarray]) as long

The principal drawing method is Draw(). Drawn data can be appended in a systematic way through a call to AppendScreen(), which offers an easy way to produce strip charts. The style of the so-drawn strip chart (either wrap-around or right-edged, with or without gap) is determined via the LeadingEdgeMotion and LeadingEdgeGapSize setttings.

Parameters:
Yarray The trace array (or portion thereof) to be appended [cast to VARIANT, by reference]. Any OLE basic type may be passed, and will be cast into a VARIANT reference. A VARIANT itself may not be passed. A call to AppendScreen() can only be made after a call to the Draw() method has been made. Therefore the parameter hDisplay is not optional and must be valid. If a user data type was used in the original call to the Draw() method, then data type of the Yarray is assumed to be the same. Otherwise, an array of doubles, singles, longs, or shorts is passed here. Internally, all data arrays are converted and stored as doubles.
hDisplay handle to the ACOP display to be appended [Long]. A call to AppendScreen() can only be made after a call to the Draw() method has been made. Therefore the parameter hDisplay is not optional and must be a valid handle returned from a prior call to Draw().
Npoints number of points to be refreshed [cast to VARIANT, by reference. Optional]. If omitted the size of the object passed as Yarray gives the number of points to be refreshed. Note that this number cannot be greater than the original number of points plotted with the Draw() method.
StartIndex starting index of the array to be appended [cast to VARIANT, by reference. Optional]. If omitted ‘-1’ is assumed. Gives the starting point of the currently displayed array where the Yarray is to be appended. Note that it is possible to append a portion of the display at any valid starting position. By default data are appending at the LeadingEdge position.
Xarray array giving the x-coordinates to be appended. [cast to VARIANT, by reference. Optional]. If selected data points are to be pair-wise appended, then Xarray should be of the same size as Yarray and indicate the X-positions of the data points to be updated.
Returns:
0 upon success, otherwise -1.

long GetDataSize ( const VARIANT FAR &  DataSize,
const VARIANT FAR &  DataSizeEx,
const VARIANT FAR &  hLink 
) [protected]

Retrieves the returned size of data set.

Visual Basic prototype: GetDataSize([DataSize] [,DataSizeEx] [,hLink]) as long

In some circumstances a server might return fewer data element than were asked for. A caller might also specify the "DEFAULT" data type and supply large buffer without knowing before hand the size of the data object being returned. In either case, the caller will need to call the GetDataSize() method to discover the size of the data object returned.

Parameters:
DataSize (optional) is the size of data set returned in the call.
DataEx (optional) is has no meaning in a call to using the TINE protocol.
hLink (optional) is the link handle assigned with a successful call to OpenLink() or AttachLink(). It can only be omitted when the ACOP component in question has only one active link bound to it.
Returns:
0 upon success, otherwise -1 if the data type of the VARIANT passed as DataSize cannot be determined.
Dim scrImage(65535) As Byte
Dim idImage As Long
Dim szImage As Long

Private Sub Form_Load()
  Dim orbit(140) As Single

  ACOP1.DeviceContext = "HERA"
  ACOP1.DeviceGroup = "HESCREEN"
  ACOP1.DeviceName = "CHANNEL1"
  ACOP1.DeviceProperty = "IMAGE"
  ACOP1.AccessMode = "POLL"
  ACOP1.AccessRate = 200
  ACOP1.AccessProtocol = "TINE"

  idImage = ACOP1.AttachLink(scrImage)

End Sub

Private Sub ACOP1_Receive(ByVal LinkIndex As Long, ByVal StatusCode As Long)
  If StatusCode <> 0 Then
    ErrorLabel.Caption = "Image Link : " + ACOP1.Status
    Exit Sub
  End If

  ACOP1.GetDataSize szImage,,idImage
    
  ShowImage scrImage, szImage

End Sub

See also:
AttachLink(), OpenLink(), Execute()

double GetDataTimestamp (  )  [protected]

Retrieves the data timestamp of the most recent completed link.

Visual Basic prototype: GetDataTimestamp() as Double

The ACOP Timestamp Property returns the UTC timestamp of seconds since Jan 1, 1970 GMT. When a timestamp of a finer granularity (namely milliseconds) is desired, you should call the GetDataTimestamp() method. This returns the same UTC timestamp which the Timestamp property shows, however as a double value, whose fractional part is valid to the nearest millisecond.

Returns:
The data timestamp of the most recent completed link as seconds (plus fraction of seconds) since Jan. 1, 1970.
See also:
AttachLink(), OpenLink(), Execute()

void SetNotificationTolerance ( BOOL  notifyOnChange,
const VARIANT FAR &  toleranceAbsolute,
const VARIANT FAR &  tolerancePercent 
) [protected]

Sets a 'notify on change' flag and optionally provides a tolerance against which a data change is measured.

Visual Basic prototype: SetNotificationTolerance(ByVal notifyOnChange [,toleranceAbsolute] [,tolerancePercent])

Normally the ACOP Receive event will be fired when incoming data arrive or when a data link shows an error condition. This method can be used the supress event notification when the incoming data do not change within a specified tolerance. Note that by setting the notifyOnChange flag to TRUE, event notification will be supressed irrespective of the polling mode. In cases where REFRESH mode is used, the first round of event supression occurs at the server, where data are not sent to the client unless they have changed, there was a error, or it is time to send a dataset according to the heartbeat. Setting notifyOnChange to TRUE will supress the heartbeat notifications in this case. In cases where POLL mode is used, all incoming data is checked at the client side before making a decision to fire the Receive event. The caller can provide either an absolute tolerance and/or a percent tolerance (expressed as a fraction) against which the incoming data can be compared prior to event notification. The change in data will be compared against the sum of the absolute tolerance and the absolute value of the percent tolerance times the previous data entry.

Parameters:
notifyOnChange applies event notification supression on change if set to TRUE or turns this feature off if set to false (the default case).
toleranceAbsolute (optional) is the tolerance value against which a change in data is determined, irrespective of the data values.
tolerancePercent (optional) is used to calculate a tolerance value based on the previously read data set.
Note:
In cases where the AttachLink() method is used to establish the data link, the incoming data will always overwrite the previous data set regardless of tolerance settings. When the OpenLink() method is used, it is the applications responsibility to obtain the data by calling the GetData() method. If the Receive event is not fired then the application will not overwrite the previous data set in this case.
Dim Xorbit(140) As Single
Dim Yorbit(140) As Single
Dim idXorbit As Long
Dim idYorbit As Long

Private Sub Form_Load()

  ACOP1.DeviceContext = "HERA"
  ACOP1.DeviceGroup = "HEPBPM"
  ACOP1.DeviceName = "WL197 MX"
  ACOP1.DeviceProperty = "ORBIT.X"
  ACOP1.AccessMode = "POLL"
  ACOP1.AccessRate = 1000
  ACOP1.AccessProtocol = "TINE"
  ACOP1.Grouped = True
  ACOP1.SetNotificationTolerance True, 0, 0.05

  idXorbit = ACOP1.AttachLink(Xorbit)

  ACOP1.DeviceName = "WL164 MY"
  ACOP1.DeviceProperty = "ORBIT.Y"

  idYorbit = ACOP1.AttachLink(Yorbit)

End Sub

See also:
AttachLink(), OpenLink()

long SetNotificationId ( long  LinkHandle,
long  LinkId 
) [protected]

Sets the notification identifier.

Visual Basic prototype: SetNotificationId(ByVal LinkHandle, ByVal LinkId) As Long

A call to AttachLink() or OpenLink() returns a LinkHandle. This handle is by default the link identifier, which is passed back to application when the Receive event is fired. If more than one data links are attached to the same ACOP control, the application must keep track of which link identifier belongs to which data set. Under some circumstances it is much easier to manage if the application can specify which link identifier it wishes to see inside an event notification (for instance the link identifier is a table entry or array index). This method allows the user to do just that.

Parameters:
LinkHandle is the link handle returned by a call to AttachLink() or OpenLink().
LinkId is the link identifier to be used inside the ACOP's Receive event when this data link returns data.
Returns:
the link identifier (identical to the LinkId parameter if no error occured).
Note:
In cases of grouped links, the link identifier of the last group item returned will be used. Hence, it is prudent to assign all links in a group the same link identifier.
Dim OnOffStatus(7) As Integer
Dim rfsrv(7) As String

Private Sub Form_Load()
  Dim id As Long
  Dim i As Integer

  rfsrv(0) = "HERFWL"
  rfsrv(1) = "HERFWR"
  rfsrv(2) = "HERFNL"
  rfsrv(3) = "HERFNR"
  rfsrv(4) = "HERFOL"
  rfsrv(5) = "HERFOR"
  rfsrv(6) = "HERFNL"
  rfsrv(7) = "HERFNR"

  ACOP1.DeviceContext = "HERA"
  ACOP1.DeviceProperty = "STATUS"
  ACOP1.AccessMode = "REFRESH"
  ACOP1.AccessRate = 1000
  ACOP1.AccessProtocol = "TINE"

  For i = 0 To 7
    ACOP1.DeviceGroup = rfsrv(i)
    id = ACOP1.OpenLink(OnOffStatus(i))
    ACOP1.SetNotificationId id, i
  Next

End Sub

Private Sub ACOP1_Receive(ByVal LinkIndex As Long, ByVal StatusCode As Long)
  If StatusCode <> 0 Then
    ErrorLabel.Caption = rfsrv(LinkIndex) + " : " + ACOP1.Status
    Exit Sub
  End If

  Call StatusChange(LinkIndex)

End Sub

See also:
AttachLink(), OpenLink()

long GetLinkStatus ( long  LinkId  )  [protected]

Retrieves the current link status for the link handle given.

Visual Basic prototype: GetLinkStatus(ByVal LinkId) as long

GetLinkStatus() is useful when data links are started with AttachLink() when 'grouped' links are in force (Grouped = True). When the group has an error condition, one way of ascertaining what the error condition is, is to call GetLinkStatus() for the link in question and examine the error code returned. Note in cases of 'grouped links', the TINE 'USE_ON_ERROR' modifier is extemely useful for identifying the 'faulty' links. Without it, you would have to call GetData() for all elements of the group when an error condition arises.

Parameters:
LinkId (optional) is the link handle assigned with a successful call to OpenLink() or AttachLink().
Returns:
The link status for the link in question, i.e. 0 upon success, otherwise the corresponding error code from the data access sublayer.
See also:
AttachLink(), OpenLink()

The documentation for this class was generated from the following files:
Generated on Wed Jan 16 14:15:51 2008 for TINE Interface to the ACOP ActiveX Control by  doxygen 1.5.4