ArrayToBuff

Description:	Returns a buffer containing the numeric data from an array.
Returns:	Numeric Buffer
Usage:	Script or steady state.
Related to:	ArrayStart | ArraySize | BuffRead | BuffToArray | BuffToParm | BuffToPointer | BuffWrite | GetByte | MakeBuff | ParmToBuff | PointerToBuff | SetByte| Array Functions
Function Groups:	Array,  String and Buffer.
Format:	ArrayToBuff(ArrayElem, N, Option, Size, Skip [,BadData])
Parameters:

ArrayElem

Required. Any array element giving the starting point for the array conversion. The subscript for the array may be any numeric expression. If processing a multidimensional array, the usual rules apply to decide which dimension should be used. Note: The array must contain numeric data only.

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, using the following table of formats: Note: For Options 7 and 9, the data is written as appropriate binary format. 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

Size

Required. Any numeric expression giving the number of digits in each datum. It has a different meaning for each option as follows: Size Size Meaning  Size Range Binary types Number of bits 1 - 32 bits 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 bits/digits/bytes to skip after writing each non-floating point element. For floating point types, this parameter must be set to 0.

BadData

Optional. A parameter that designates how invalid data is to be handled, according to the following table. Defaults to 0 if missing or invalid. BadData Invalid Data Type 0 Output to buffer as valid 0s 1 Causes buffer to be invalid 2 Output to buffer as valid 0s

Comments:

This function may only be used with arrays containing numeric data. It is useful for writing I/O drivers and saving arrays of data in RAM with a fraction of the memory requirement.

Example:

In the following example, assume that array x is a one-dimensional array containing the values 4.5, invalid, and 200:

If ! Valid(buff);
[
  buff = ArrayToBuff(x[0] { Starting element },
                    3 { Number of elements to process  },
                    7  { Type - IEEE floating point },
                    1  { Single precision },
                    0  { Skip is ignored },
                    2  { Use 0 for each invalid value });
  BuffRead(buff   { Buffer to read },
           0 { Starting offset },
           "%3b%3b%3b" { Type IEEE floating point binary },
           a1, a2, a3 { Variables to hold the values });
]

This code produces a formatted buffer called buff that holds 3 float values (written in binary format), each corresponding to an element in the array. The second value in the array is invalid - in the buffer, it will be a valid 0. The values of a1, a2 and a3 then will be 4.5, 0 and 200 respectively.