cardBlocks

cardBlocks elements contain preCard, card, and postCard elements that define the data required for a Modbus DynaCard type.

This element is:

Case sensitive

Required in a DynaCard-enabled, Modbus device template file

Used once per DynaCard type

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

Example

Click here to see an example of the element

</card>

</card>

</card>

</postCard>

</cardBlocks>

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
cardOrdinal	cardOrdinal specifies the dynagraph card ordinal a card block represents. The cardOrdinal value must be mapped to a dgOrdinals value. Value: Non-negative whole number that represents a valid DynaCard type enumeration. For example, a current card in CygNet SCADA is typically enumerated with a 0 (zero).
downholePtCount	downholePtCard specifies the number of downhole points (i.e., load-position pairs) to retrieve for a DynaCard. The number of points retrieved affects the precision of the resulting graph. Value: Must be a positive whole number.
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.
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.
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.
surfacePtCount	surfacePtCard specifies the number of surface points (i.e., load-position pairs) to retrieve for a DynaCard. The number of points retrieved affects the precision of the resulting graph. Value: Must be a positive whole number.
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.

Attribute

Description

cardOrdinal

cardOrdinal specifies the dynagraph card ordinal a card block represents. The cardOrdinal value must be mapped to a dgOrdinals value.

Value:

Non-negative whole number that represents a valid DynaCard type enumeration. For example, a current card in CygNet SCADA is typically enumerated with a 0 (zero).

downholePtCount

downholePtCard specifies the number of downhole points (i.e., load-position pairs) to retrieve for a DynaCard. The number of points retrieved affects the precision of the resulting graph.

Value:

Must be a positive whole number.

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.

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.

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.

surfacePtCount

surfacePtCard specifies the number of surface points (i.e., load-position pairs) to retrieve for a DynaCard. The number of points retrieved affects the precision of the resulting graph.

Value:

Must be a positive whole number.

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.

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.

Code

Name

Description

Read Coils

Reads contiguous coil statuses from 1 - 2000. Registers must be read-only Boolean.

Read Discrete Inputs

Reads contiguous discrete input statuses from 1 - 2000. Registers must be read/write Boolean.

Read Holding Registers

Reads contiguous contents of a block of holding registers. Registers must be read-only 16 or 32 bit.

Read Input Registers

Reads contiguous input registers from 1 - 125. Registers must be read/write 16 or 32 bit.

Write Single Coil

Writes ON or OFF to a single coil. Registers must be read/write Boolean.

Write Single Register

Writes data to a single holding register. Register must be 16 or 32 bit.

Read Exception Status

Reads the contents of eight exception status outputs in a remote device.

Write Multiple Coils

Writes ON or OFF to multiple coils in sequence. Registers must be Boolean.

Write Multiple Registers

Writes data to a block of contiguous registers from 1 - 123. Registers must be 16 or 32 bit.