This statement copies raw data from one location to another, bypassing the Equinox data conversion mechanism. The first argument, DataItem, is the name of a variable, field, workarea, or the special constant PTR (indicating a pointer). Equinox uses this argument to deduce the size of the data to be copied. FromItem specifies the current location of the data and should be the name of a variable, field, or workarea (or part thereof). ToItem indicates the target location.

You may pass structures containing pointers, by using the constant PTR as the first parameter: a pointer to the second parameter is written to the third parameter. If you use pointers, note the following:

• The address of an item is not guaranteed to stay the same. Refresh the item in the structure before you use it.
• Pointers in the Intel implementations are (4-byte) pointers.
• It is not possible to make Equinox data items point to external data. There is no mechanism for using pointers written into structures by external routines. These problems may be resolved by writing external calls to do the data manipulation required.

If ToItem is an assignable string expression (for example s[1] or mid(s,4)), Bcopy performs a cut and paste operation on it; in other words any data in the string expression is removed, and the data in FromItem is inserted. If there is no data at that point in the string because the currently assigned length is shorter, the new data is inserted at the location specified, and any unwritten space before is set to spaces.

This statement may be used to prepare otherwise unsupported data areas such as C structures for passing to external software. However it can also be used to copy data from one place to another without Equinox's automatic data conversion intervening. In particular, vector expressions are supported in all three parameters, which allows arrays to be simply transferred to and from memos, for example.

The size of an array source is the size of its readable data, and the size of a destination array is its current writable size; in practice what this means is that source string arrays contain the sum of the assigned length of all the strings in it, destination string arrays are the size of the declared length of all the items, and destination memo arrays are the size of the current declared length of the elements - Bcopy does not change their declared lengths (see the MaxLen and SetMaxLen statements).

This example copies a string into a byte array, and prints the ASCII values of the characters. It then encrypts the string by adding one to each character, and copies it back again:

string s

s = "Hello"

block

Byte v[Len(s)]
Bcopy v, s, v
v += 1
Bcopy v, v, s

end block

Print s

This example sets up a structure and calls the C function SetDataPoint. The function expects a pointer to the following structure:

• unsigned char type: 1 = modify value on return
• Int PointNum: 0-63
• double value: the data value

Zero is returned if no error occurs. Note that ReadPoint and UpdatePoint are local procedures.

external "Eqgraph32.dll" SetDataPoint Ptr String Returns Int

string PointStruct(13)
int reply
number dpoint

...

PointStruct[1] = Chr(1)

For i = 0 To 63

| Get the Next value
ReadPoint i, dpoint | routine not discussed here

| call the routine and check the return value
Bcopy i, i, Mid(PointStruct, 2, 2)
Bcopy dpoint, dpoint, Mid(PointStruct, 4, 8)
SetDataPoint PointStruct, reply

if reply then Alert "SetDataPoint error" & reply

| retrieve the modified value and store it
Bcopy dpoint, Mid(PointStruct, 4, 8), dpoint
UpdatePoint i, dpoint | routine not discussed here

next