block

The blockn element defines constraints used to map register data to data group elements (DataGroupElement) within a CygNet data group. Each block defines a structure that reads or writes contiguous registers. Multiple blocks can be used, depending on the requirements of the dependent data group(s). CygNet blocks are not restricted by the Modbus maximum message size of 250 data bytes; you can specify any number of contiguous registers to retrieve per block when using the regCnt attribute.

The first block is always block1. Subsequent blocks are blockn, where n represents the block number. Blocks must be enumerated consecutively; block enumerations can only be used once. So if you use three blocks, call the blocks block1, block2, and block3. Fewer blocks means fewer communication transactions between the CygNet host and field device(s). It might be more efficient for you to use fewer blocks and bring back extra bytes than to create numerous blocks with few bytes.

To read to or write from a single register, either define only one data element in the applicable data group or use a single-element data group.

This element is:

Case sensitive
Required in every modbusReadBlocks/modbusWriteBlocks, readBlocks/writeBlocks, and card element
Used 1 or more times per modbusReadBlocks/modbusWriteBlocks, readBlocks/writeBlocks, and card element

To learn about how this element relates to other elements in a CygNet device template file, see Device Template File Hierarchy.

Example

Attributes

The following table lists and describes attributes generally applicable to this element. However, not all of the attributes listed here are applicable to all EIEs. Additionally, some attributes are required for use in every device template file of a certain EIE, but others may be used on a case-by-case or device-by-device basis, depending on your specific needs. All attributes in templates are case sensitive; but the case sensitivity of attribute values is based on context.

Note: Occasionally, device template files for different EIEs use attributes of the same name that do different things. Efforts are made in this document to highlight cases where an attribute by one name does different things in different EIEs.

Attribute	Description
cardIncrement	cardIncrement specifies a number of registers by which to increment when multiple dynagraph cards are available. The number of cards supported for each card type is defined by protocol. Value: Must be a positive whole number.
cardRep	cardRep specifies the type of DynaCard data represented by a card or block element. Value: Must be defined at the card or block level for every block included in a card element. downhole: Indicates that the data source is downhole. If set to downhole, downholePtCount must also be defined in the parent or grandparent element. none: Indicates that the data source is neither downhole nor surface. surface: Indicates that the data source is surface. If set to surface, surfacePtCount must also be defined in the parent or grandparent element.
forceSave	forceSave specifies whether or not to save a data group’s transactions to the DDS whenever a data group request is issued by a UIS command. (Data group transactions are created for all requests issued directly from device editors in CygNet Explorer.) There are cases where the device driver forces every transaction of a particular data group to be saved to the DDS, regardless of the use of forceSave. For example, some device restrictions allow data to be retrieved only once, and FMS data groups always save transactions. If this attribute is not defined in a given data group, that data group uses its default save behavior, which varies by data group. Value: Must be a Boolean value true or false.
funcCode	funcCode specifies the Modbus function code for accessing a register or block of registers. Value: Must be a positive whole number. Must be a valid and supported Modbus function code. See Function Codes.
len	len specifies the number of bytes in a data group element or register. Value: Must be a positive whole number.
newTx	newTx specifies that a new message transaction starts at the block element in which newTx is defined and includes block data for all subsequent blocks until another definition of newTx set to true is encountered. Value: Must be a Boolean value true or false.
ordIncrement	ordIncrement specifies how many registers make up an increment of registers. It is always used in combination with regNum, which specifies a starting register number from which to increment. These two attributes are used to specify one or more groups of registers that correspond to data group ordinals. ordIncrement always depends on regNum, but regNum does not depend on ordIncrement. Optionally, use regNum_ordn in place of ordIncrement + regNum. Value: Must be an integer.
regBitLen	regBitLen specifies the length in bits of each register returned from the device for the specified funcCode. This setting can change from section to section and from register to register in the device. Refer to field device documentation for these settings. Value: Must be a positive whole number. Modbus coil data groups using function code 1, 2, 5, or 15 must use regBitLen, not regByteLen. See also regByteLen.
regByteLen	regByteLen specifies the length in bytes of each register returned from the device for the specified funcCode. This setting can change from section to section and from register to register in the device. Refer to field device documentation for these settings. Value: Must be a positive whole number. Modbus coil data groups using function code 1, 2, 5, or 15 must use regBitLen, not regByteLen. See also regBitLen.
regCnt	regCnt specifies the number of registers to be returned in a block. CygNet blocks are not restricted by the Modbus maximum message size of 250 data bytes; you can specify any number of contiguous registers to retrieve per block when using the regCnt attribute. Value: Must be a positive whole number.
regNum	regNum defines a starting register number. To make this attribute meter specific, append _ordn to the attribute. For example, regNum_ord1. To define a logical register number, as with Modbus devices, use regNum in conjunction with regOff. To make this attribute request-type specific for use in DynaCard preCard and/or postCard elements, append _singleCard or _multipleCard to the attribute. For instance, regNum_singleCard. regNum without the appendix cannot be used in the same element as regNum_singleCard or regNum_multipleCard. If you use _singleCard or _multipleCard, you must also use the other in the same block element. Value: Must be a positive whole number.
regOff	regOff defines a register offset that translates a logical register number into a physical register number. It is always used in conjunction with regNum. It may be defined in the same element as regNum, or it may be defined in a parent element then inherited by one or more regNum attributes. regOff enables you to translate Modbus coil/register numbers into data addresses used by field devices. Modbus coil/register numbers are not the same thing as data addresses. For example, the Modbus register number 30001 typically uses the data address 0, which means that you would want to offset a regNum value of 30001 by -30001 in order to return a data address of 0 (or 0x0000). Typical offset constants are as follows: -1 -10000, -10001 -30000, -30001 -40000, -40001 You must consider the Modbus coil/register range convention you follow and the data addressing convention you follow. In both cases, know the range starting number and the extent of the range. The offset can be determined from the field device manual or register map. Value: Must be an integer.
toDevice	toDevice specifies that a block element first writes a value to a field device before the rest of a read message is executed. Used when a specification must be sent before the field device "knows" what to load and return. Value: Must be a Boolean value true or false.
txMaxRegCnt	txMaxRegCnt specifies the maximum number of registers that may be communicated in a single transaction. This attribute is optional and intended to provide a way to make messages for a single block smaller than the Modbus maximum message size of 250 data bytes. How many registers you read or write within byte constraints depends on the size of the registers with which you are communicating. txMaxRegCnt is used in conjunction with the regCnt attribute. regCnt specifies the number of registers to be returned in a single block; txMaxRegCnt merely constrains the size of the message(s) used to communicate registers. For example, if you want to retrieve 125 2-byte registers in a single message, set regCnt to 125 and do not use txMaxRegCnt. But if you want to retrieve 125 2-byte registers in five messages, set regCnt to 125 and txMaxRegCnt to 25. Value: Must be a positive whole number. Cannot exceed the number of registers that the Modbus maximum message size of 250 data bytes can accommodate.
type	type defines the appropriate data type for one or more DataGroupElement elements; it can be inherited from a parent element. Value: bin.hex: Binary hex boolean: Boolean i1: Character i2: Short integer i4: Integer i8: Integer r4: Float r8: Double ui1: Byte ui2: Unsigned short integer ui4: Unsigned integer ui8: Unsigned integer string: String struct: Structure See also sourceType.

Function Codes

The following Modbus function codes are supported by CygNet.

Code	Name	Description
1	Read Coils	Reads contiguous coil statuses from 1 - 2000. Registers must be read-only Boolean.
2	Read Discrete Inputs	Reads contiguous discrete input statuses from 1 - 2000. Registers must be read/write Boolean.
3	Read Holding Registers	Reads contiguous contents of a block of holding registers. Registers must be read-only 16 or 32 bit.
4	Read Input Registers	Reads contiguous input registers from 1 - 125. Registers must be read/write 16 or 32 bit.
5	Write Single Coil	Writes ON or OFF to a single coil. Registers must be read/write Boolean.
6	Write Single Register	Writes data to a single holding register. Register must be 16 or 32 bit.
7	Read Exception Status	Reads the contents of eight exception status outputs in a remote device.
15	Write Multiple Coils	Writes ON or OFF to multiple coils in sequence. Registers must be Boolean.
16	Write Multiple Registers	Writes data to a block of contiguous registers from 1 - 123. Registers must be 16 or 32 bit.

block

Example

Attributes

Value:

Value:

Value:

Value:

Value:

Value:

Value:

Value:

Value:

Value:

Value:

Value:

Value:

Value:

Value:

Function Codes