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 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 units to skip after each element is read. 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.

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.