PointerToBuff

(Engine-Level Function)

Description: Returns a buffer containing the numeric data from the variables pointed at by each element of the array.
Returns: Buffer
Usage: Script or steady state.
Function Groups: Array,  String and Buffer
Related to: BuffToArray | BuffToParm | BuffToPointer | GetByte | ParmToBuff | SetByte
Format: PointerToBuff(ArrayStart, N, Option, Size, Skip)
Parameters:  
ArrayStart
Required. Any expression that specifies the starting array element. This array contains the pointers to the variables whose values will be written to a buffer. If processing a multidimensional array, the usual rules apply to decide which dimension should be used.
N
Required. Any numeric expression giving the number of array elements to convert starting at the element given by the first parameter.

If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
Option
Required. Any numeric expression that specifies the format of the buffer write:

Option

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 written as appropriate binary format.
Size
Any numeric expression giving the number of digits in each datum. Size has a different meaning for each option as indicated below:

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
Any numeric expression giving the number of buffer bits/digits/bytes to skip after writing each non-floating point element. In binary modes, the following values are supported: 8, 16, 32, and 64. For floating point types, this parameter must be set to 0.
Comments:

This function may only be used with pointers pointing at numeric data. Any invalid array elements, or invalid data pointed at by array elements are written to the buffer as formatted zeroes. This function is useful for writing I/O drivers and saving arrays of data in RAM with a fraction of the memory requirement.

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:

buff1 = PointerToBuff(dataPtr[0]{ Starting point in array },
                      100 { No. of elements to convert },
                      5 { Write as ASCII hex },
                      4 { Number of bytes per },
                      0 { No skip between writes });

This produces a formatted buffer 400 bytes long (100 four byte groups). Each 4 bytes is a hex number corresponding to a variable pointed at by an element in the array. Invalid array elements and invalid data are written as 0.