BuffToParm

(Engine-Level Function)

Description Convert buffer of numeric data to parameters. This function reads module parameters from a formatted buffer containing numerical data and returns the number of data items read.
Returns Numeric
Usage Script Only.
Function Groups String and Buffer,  Compilation and On-Line Modifications
Related to: BuffToArray | Parameter | ParmToBuff
Format BuffToParm(Object, Index, Buffer, Offset, N, Option, Size, Skip)
Parameters  
Object
Required. The object value of the module containing the destination parameters.
Index
Required. Any numeric expression giving the first parameter to read, starting at 1.
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.
N
Required. Any numeric expression giving the number of parameters to read from the buffer. If there are fewer actual parameters than N specifies, this function continues to the last parameter and then stops.
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. 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. It reads the buffer, and places the data into module parameters. Normally, the module parameters will be variables. If a parameter is not a variable, then nothing will be assigned to that parameter, and this statement reads the next datum and continues on to the next parameter (if any). 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 parameters are set to invalid.

The return value is the number of data read and can be used as an error check (non-zero indicates an error).

This function is typically used in an I/O driver module to convert serial port or shared RAM data to VTScada variables.

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:

In this example, suppose that a module is started with the statement (a.k.a. module call):

  ReadIEEE(1, "PLC", 2, x, y, z);

and that the module ReadIEEE contains the following script:

  If 1 Main;
  [
    BuffToParm(Self() { Data goes in this module's parms },
               4 { Start at parm 4 (skip first 3 ) }, 
               Response { Formatted buffer to be read }, 
               12 { Skip first 12 characters, 0 to 11 }, 
               NParm(Self()) - 3
               { Compute number of parms to read }, 
               7 { Format is IEEE floating point }, 
               2 { Double precision }, 
               1 { Skip 1 byte between each double });
  ]

This example reads IEEE double precision numbers from a buffer and places them in the module ReadIEE's parameters. The bytes 0 to 11 of response are skipped. Bytes 12 to 19 are converted from IEEE format and placed in x. Byte 20 is skipped (the skip parameter indicates 1 byte). Bytes 21 to 28 are converted and placed in y. Byte 29 is skipped. Bytes 30 to 37 are converted and placed in z. Reading ceases, (NParm(Self) - 3 equals 3, or three parameters have been read).