BuffToPointer

(Engine-Level Function)

Description Converts a buffer of numeric data to array of pointers. This function reads from a formatted buffer containing numeric data, writes to locations specified by an array of pointers, and returns the number of elements read.
Returns Pointer array
Usage Script Only.
Function Groups Array, String and Buffer
Related to: BuffToArray | BuffToParm | New | PointerToBuff
Format BuffToPointer(ArrayElem, N, Buffer, Offset, Option, Size, Skip)
Parameters  
ArrayElem
Required. Any array element giving the starting point in the pointer array. The subscript for the array may be any numeric expression.
N
Required. Any numeric expression giving the number of items to read. If N extends past the upper bound of the array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Buffer
Required. Any text or buffer expression to read.
Offset
Required. Any numeric expression giving the starting buffer position for the read in characters (bytes), starting at 0.
Option

Required. Any numeric expression that specifies the format of the buffer read. This can be one of:

Option

Buffer Format

0

Unsigned binary (low byte first)

1

Signed binary (low byte first)

2

BCD (binary coded decimal) (low byte first)

3

ASCII octal (high byte first)

4

ASCII decimal (high byte first)

5

ASCII hex (high byte first)

6

ASCII floating point (high byte first)

7

IEEE float/double (low byte first)

8

<obsolete>

9

Allen-Bradley® PLC/3 floating point

10

VAX single precision floating point

For Options 7 and 9, the data is read as appropriate binary format.

Size

Required. Any numeric expression giving the number of digits in each datum. Size is measured in different ways for each format option (specified in previous parameter), as indicated in the following table:

Option

Size Meaning

Size Range

Binary types

Number of bits

 The following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64

BCD

Number of 4-bit digits

1 - 8 digits

ASCII types

Number of bytes

1 - 32 bytes

Float types

Precision

1 for single precision,

2 for double precision.

Skip
Required. Any numeric expression giving the number of buffer units to skip after each element is read. In binary modes, the following values are supported: 8, 16, 32, and 64.
Units are bits for Options 0 and 1, BCD digits for type 2, and characters or bytes for all others.

Comments:

This function may only be used with buffers containing formatted numeric data. Illegal characters that are imbedded in the ASCII string stop further interpretation and are ignored. If an illegal character or the end of a buffer is encountered before a valid number, the remaining elements are set to invalid. As each item is read from the buffer, the result is stored to the location pointed to by the element of the array. If an element is invalid, or doesn't contain a pointer, then nothing happens and processing continues with the next item/element.

The return value is the number of array elements read. This may be used as an error check - if the return value is not zero, then one or more array elements were not read.

In binary modes, for the Size parameter, the following values are supported: 1 (in unsigned mode), 4, 8, 16, 32 and 64. For the Skip parameter, the following values are supported: 8, 16, 32, and 64.

Size and Skip values not in those ranges will only work if their combined value is a multiple of 8. For instance, a Size of 12 and a Skip of 4 will work. A Size of 48 and a Skip of 0 will work. When Skip + Size is not a multiple of 8, the behavior of this function is undefined.

If your values are of Size 1 (i.e. a single bit), use unsigned mode. A Size of 1 is not supported for signed values.

Example:

Assume that the pointer array has been initialized as shown:

  Destination[0] = &StationFlow;
  Destination[1] = &StationPower;
  Destination[2] = &StationIntruder;
  Destination[3] = &StationOK;
  Destination[4] = &StationPressure;

Now execute the statement:

    BuffToPointer(Destination[0] { Starting element },
                  5 { No. of elements to read }, 
                  Response { Text expression to read }, 
                  0 { Starting offset in buffer }, 
                  2 { Read BCD format }, 
                  4 { 4 BCD characters is 2 bytes }, 
                  0 { Don't skip anything });

This reads 5 BCD format numbers into variables pointed to by elements 0 to 4. Each BCD number has 4 digits, which occupy 2 buffer bytes. This will set the variables StationFlow, StationPower, StationIntruder, StationOK, and StationPressure to the values read from the buffer.