Copyright: Copyright © 1997 Automation Consulting Services


Contents

Software License

Introduction

Hardware Lock

Cabling

Properties

Methods

Error Codes

Exceptions

Press <F1> for Help on Help.

This help file is Copyright © 1997 Automation Consulting Services, Inc.

Subject to change without notice.

Last revised: 18 September, 1997


Introduction

The ACS MODBUS Driver ActiveX Control is a software component that allows application programs written in a wide variety of languages to communicate with devices that understand the Gould MODBUS RTU protocol.

The Driver is provided as an ActiveX component (formerly known as OLE Custom Control or “OCX”). It allows your program to communicate with MODBUS devices by invoking methods and setting properties. The Driver control handles the MODBUS protocol implementation, variable conversion, error checking, serial port management, and so on. Information is passed to and from the control (and hence the MODBUS device) using the host language’s native variable types.

The Driver ActiveX control can be used with any language or development environment that supports ActiveX controls, including C++, Visual Basic, Delphi, and many others. It supports the Microsoft Windows 95 and Windows NT operating systems.

The Driver directly implements all the commonly used MODBUS commands. If your application requires non-standard commands, the control provides methods that allow you to “build” your own MODBUS command frames and send them. In addition, programs that use the Driver control can act as MODBUS “master” or “slave” devices, either initiating or accepting commands.

 For more information, see Building MODBUS Driver Applications

 Back to Contents


Building MODBUS Driver Applications

Most applications that use the MODBUS Driver ActiveX control will perform the following steps:

Driver Control registration

Before you can use the Driver ActiveX control, you’ll need to make your programming language aware of it. This process is called “registration.”

Most languages provide a simple way of adding new ActiveX components to a project. In Visual Basic 5, for example, you can register the Driver ActiveX control by selecting the “Project / Components…” command, clicking the “Browse…” button, navigating to the directory where the Driver control is located, and double-clicking the file MBDRVCTL.OCX. Other languages provide similar facilities.

You only need to perform this registration step once, the first time you want to use the Driver ActiveX control. Once the control is registered, it will be available to all applications on the host system.

Adding the Control to your project

Once the control is registered, you need to add it to your project. Again, the exact procedure will vary according to the language, but most languages follow a model similar to Visual Basic.

In VB5, you can add the Driver ActiveX control to a project by selecting the “Project / Components…” command and checking the box next to “MODBUS Driver ActiveX Control.”  This will make the control available on the VB tool palette.

Adding an instance of the Control

To be able to use the Driver, you must add an instance of the Driver ActiveX control to your program. For languages like Visual Basic, this is as simple as “drawing” a MODBUS control on one of your application’s forms.

The MODBUS Driver ActiveX control looks like this on the VB tool palette:

Once you’ve drawn a MODBUS control on your VB application’s form, it will look something like this:

C++ users can create an instance of the control in one of two ways. The simplest way is to draw a MODBUS control on one of your application’s dialog boxes, much as one would in VB. When you add the Driver ActiveX control to your C++ project, the development environment will create a “wrapper” class for it. This class, which will probably be called something like CMBDrvCtrl, allows you to access the control’s properties and methods using ordinary C++ member functions. So, you can create an instance of the MODBUS ActiveX control anywhere in your program just by declaring or allocating a variable of the “wrapper” class.

Setting Properties

Once the control exists, you can use your development environment’s “object inspector” or property-sheet examiner to set the control’s basic properties, such as communications port, baud rate, and so on. These “persistent” properties will be saved with the control and hence be “remembered” from session to session.

If your application will not be changing these properties, it makes sense to set them once and store them with the control, rather than setting the properties each session under program control.

Sending MODBUS commands

If the communications parameters are set, you are ready to send MODBUS commands. The Driver ActiveX control has methods for the most commonly-used MODBUS commands. To send a command, you simply need to invoke the correct method.

For example, let’s suppose that you want to read the current contents of Input Registers 30010 through 30020 from a MODBUS device whose address is 9. Consider the following Visual Basic code fragment:

Dim status As Integer, V As Variant, n As Integer

status = MB.ReadInputRegisters(9, 30010, 11, V)

If status <> 0 Then

MsgBox "Read Input Registers failed, error: " + MB.LastErrorString(), _

vbOKOnly Or vbExclamation, "Read Input Registers Test"

Else

For n = 0 to 10

Debug.Print 30010 + n; " = "; V(n)

Next n

End If

Note. This code assumes that the current form contains an MODBUS Driver control named “MB.”

The code segment begins by requesting the values of 11 Input Registers starting at 30010 from the MODBUS device whose address is 9 using the ReadInputRegisters method. When the method returns, the variable status will contain either 0 for success or an error code.

If the Read Input Registers request fails, status will be nonzero, so the code fragment displays a message box. The MsgBox statement uses the LastErrorString property to retrieve a text error message so the user will easily be able to tell what went wrong.

If the request succeeds, the requested register values will be stored in the Variant V as an integer array. The contents of register 30010 will be in V(0); the contents of 30011 will be in V(1); and so on. The example simply uses the VB Debug object’s Print method to display the contents of the 11 registers in the Immediate window.

Obviously, a real application would display these values in a more useful way, or otherwise act on the data values. However, the example should show you the basic procedure used when calling the MODBUS Driver ActiveX control to send MODBUS commands.

Additional Capabilities

Most MODBUS Driver applications will probably find the control’s normal MODBUS command methods contain all the functionality they need. Should the situation arise, the Driver ActiveX control provides some specialized features:

•	Incoming command processing. Most MODBUS applications will probably operate as MODBUS “masters,” that is, they will send command and wait for replies. However, the Driver does support “slave” operation. If you need to accept commands from MODBUS devices, see the Receive method section.

•	Non-standard commands. The MODBUS Driver ActiveX control contains a generous subset of the commands allowed by the MODBUS protocol. If you find that the Driver does not provide a dedicated method for a MODBUS command that you need to send, you can employ the User command frame methods to build and send unsupported commands.

 Back to Contents


Software License

IMPORTANT!  The enclosed materials are provided to you on the express condition that you agree to this Software License.  By opening the diskette envelope or using any of the enclosed diskette(s) you agree to the following provisions.  If you do not agree with these license provisions, return these materials to Automation Consulting Services, Inc., in original packaging with seals unbroken, within 3 days from receipt, for a refund.

1.	This software and the diskette on which it is contained (the “Licensed Software”), is licensed to you, the end user, for your own internal use.  You do not obtain title to the Licensed Software or any copyrights or proprietary rights in the Licensed Software.  You may not transfer, sub-license, rent, lease, convey, copy, modify, translate, convert to another programming language, decompile, or disassemble the Licensed Software for any purpose.

2.	The Licensed Software is provided “as-is”.  All warranties and representations of any kind with regard to the Licensed Software are hereby disclaimed, including the implied warranties of merchantability and fitness for a particular purpose.  Under no circumstances will the Manufacturer or Developer of the Licensed Software be liable for any consequential, incidental, special, or exemplary damages even if apprised of the likelihood of such damages occurring.  Some states do not allow the limitation or exclusion of liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you.

Incorporated Driver Amendment

If you own OEM Version of the ACS MODBUS driver, this license is amended to provide for the free or for-profit distribution of software incorporating MODBUS Driver code as follows: you may distribute executable programs containing the complete and unaltered ACS MODBUS Driver (Incorporated Version).  The Incorporated Version Libraries may not be copied, sold, modified, distributed, or used by more than one user at a time; they are treated as Licensed Software as described above.  You can only distribute the Driver as a part of self-standing executable code (EXE files).  No royalties or additional licenses are required to distribute such standalone programs.

For Windows DLLs, you may distribute the DLL (distribution) version without royalties, but you may not distribute the Development (VBX) version.  It is treated as Licensed Software as described above.

For the MODBUS Driver ActiveX control, you may distribute the ActiveX file MBDRVCTL.OCX only with your applications. The printed documentation and help files are considered Licensed Software as indicated above. Specifically, you may not sell or otherwise distribute the MODBUS Driver ActiveX control other than with an application or for use other than as a communications component.

 Back to Contents


Cabling

Normally, your ACS software will be supplied with a cable suitable for connecting the IBM PC or compatible to the MODBUS device.

However, some of our customers find that they need to make their own cables.  This section describes the cable and pinouts at each end of the connection.  The serial port pinouts are included for reference, since they are not often described in computer manuals.

The Cable

You can use the Driver with a three-wire (Transmit Data, Receive Data, and Ground) cable.  ACS uses the following cable:

Conductor	Signal	IBM PC Pin	IBM AT Pin	Device Pin
1	Ground	7	5	7
3	TD	2	3	3
4	RD	3	2	2
Unfortunately, not all MODBUS devices have standard serial ports.  You may need to experiment in order to find the correct cabling setup.  A “breakout box” or similar device can be very helpful while trying to set up a serial communications link.

PC Serial Port

The IBM PC serial port is a DB25M (25-pin Male) connector.  Here are its pinouts (pins not listed are No Connection):

Pin	Direction	Signal
1	Shield Ground
2	Output	Transmit Data
3	Input	Receive Data
4	Output	Request to Send
5	Input	Clear to Send
6	Input	Data Set Ready
7	Signal	Ground
8	Input	Carrier Detect
9	Output +	Transmit Current Loop
11	Output -	Transmit Current Loop
18	Input +	Receive Current Loop
20	Output	Data Terminal Ready
22	Input	Ring Indicator
25	Input -	Receive Current Loop
Note:	Only strictly IBM-compatible serial ports implement the 20ma current loop interface.

AT Serial Port

The IBM PC AT serial port is a DB9M (9-pin Male) connector.  Here are its pinouts:

Pin	Direction	Signal
1	Input	Carrier Detect
2	Input	Receive Data
3	Output	Transmit Data
4	Output	Data Terminal Ready
5		Ground
6	Input	Data Set Ready
7	Output	Request to Send
8	Input	Clear to Send
9	Input	Ring Indicator
 Back to Contents


Hardware Lock

Unfortunately, software piracy is a problem that plagues all program developers: the temptation to copy an unprotected disk is great, and there is little actual danger to the pirate.  But copy protection often offends users and sometimes involves unnecessary “hassles”.  In order to keep everyone honest with a minimum of trouble for the user, ACS has decided to issue all of its single-user Driver products in copy-protected form.

Note.	OEM versions of the Driver ActiveX control are not copy protected.

Hardware Lock

A Hardware Lock protects the single-user Driver.  Programs protected with a Hardware Lock come on ordinary floppy diskettes.  You can (and should) make backup copies of the protected files, using the DOS diskcopy command if you wish.  The protection is incorporated into the files themselves and into the locking device.

The Hardware Lock itself is a small device resembling a “gender changer.”  It has two 25-pin connectors on it, one male and one female.

When you run a program protected with a Hardware Lock, the software will periodically examine your computer’s parallel printer port.  If the correct Hardware Lock is found, the program runs normally.  If the locking device is not present, the program will not operate.

To use the Hardware Lock, simply copy the original program diskettes into a directory on your hard disk.  Next, plug the male end of the Hardware Lock device into your computer’s parallel printer port (LPT1).  If there is a printer already attached to your system, simply plug its cable into the female end of the Hardware Lock.

Once you have attached the locking device, you are ready to run the software.  Your computer should operate just as before; the device is only active when the software specifically queries it.  The Lock is also transparent to printing.

By default, the Driver looks for the Hardware Key on printer port LPT1.  To change the port where the key is found, use the KeyPort property.

If you are using the default port, LPT1, there is no need to set the KeyPort property.  The Driver will return an error code of -4 if the key is not detected.

 Back to Contents


Error Codes

The MODBUS Driver ActiveX control reports errors in two different ways, by using numeric error codes and by throwing exceptions. Error codes are used to report communications problems, while exceptions are reserved for more severe conditions that may indicate faults in your application code.

For example, if you send a MODBUS command, and no reply is received, the Driver will report a Timeout error. However, if you attempt to tell the Driver to send a command to an illegal MODBUS address, or if you supply a parameter (such as a register address) with an invalid value, the control will throw an exception.

Error codes are also used to indicate problems reported by the MODBUS device. For example, most MODBUS devices implement only a subset of the available commands. If you use a Driver method to send a command that the device doesn’t support, it will return an error code.

Here are the currently defined error codes:

Error	Code	Constant
No error	0	mbdError_None
Hardware Key not found	-4	mbdError_NoKey
Receive Operation Failed	-3	mbdError_NoRecv
Could not send frame	-2	mbdError_NoSend
Timeout	-1	mbdError_Timeout
Bad frame received	1	mbdError_BadFrame
CRC error	2	mbdError_CRC
Returned Frame check failed	3	mbdError_RetCheck
MODBUS 01: Illegal Function	101	mbdError_MB_Func
MODBUS 02: Illegal Data Address	102	mbdError_MB_Addr
MODBUS 03: Illegal Data Value	103	mbdError_MB_Data
MODBUS 04: Failure in Associated Device	104	mbdError_MB_Fail
MODBUS 05: Acknowledge	105	mbdError_MB_Ack
MODBUS 06: Busy, Rejected Message	106	mbdError_MB_Busy
MODBUS 07: NAK	107	mbdError_MB_NAK
MODBUS 08: Memory Parity Error	108	mbdError_MB_Parity
MODBUS errors are handled by adding 100 to the value returned in the error frame from the MODBUS device. As a consequence, if you encounter an error greater than 108, subtract 100 from the number to obtain the MODBUS error identification number.

Such error numbers are not defined in the protocol specification, so you will need to consult your device’s documentation to determine their meaning.

 Back to Contents


Exceptions

The OLE specification provides a way for an embedded control (like the Driver ActiveX control) to signal serious error conditions to its host. To signal such an error condition, the control can “throw an exception.”

The MODBUS Driver ActiveX control uses exceptions for serious error conditions, either internal errors or problems that indicate faults in your application code. For example, if your code tells the Driver to send a command to an illegal MODBUS address, or if you supply a parameter (such as a register address) with an invalid value, the control will throw an exception.

The exception mechanism is very different from the numerical error codes used to signal communications problems. An exception causes the currently executing method to abort immediately and send a special signal to the host (“container”). How the host reacts to this signal depends on the programming language.

By default, most languages and development environments will stop your application and display an error box when an exception occurs. Depending on your programming language’s features, you may be able to prevent or alter this behavior.

C++, for example, provides the try … catch construct to handle exceptions. By enclosing a Driver call in a try block, you can intercept and handle any exceptions that may occur.

Visual Basic provides exception handling via the on error goto statement. When an exception occurs after an on error goto statement, control flows to the statement named in the on error command. Your code can then determine what action to take and resume normal execution.

It should be stressed that you normally shouldn’t need to worry about the exception mechanism. Once your code is debugged, the Driver control should never need to throw an exception. If an exception does occur in debugged code, the situation is probably very serious.

During debugging, exceptions are actually very valuable. By stopping the program and signaling a serious error, the Driver is telling you that there is probably a bug in your code. This makes finding errors much quicker.

“Routine” communications errors (such as Timeouts and CRC errors) do not cause the Driver to throw exceptions. Instead, these problems are reported via the error code returned by each method. Your code needs to check for and handle these errors, obviously, but you probably don’t need to worry about exception handling for most applications.

 Back to Contents


Variants

The MODBUS Driver ActiveX control makes extensive use of the OLE Variant data type. The major reason for this is that there is no other standard way to safely pass arrays between the host application and the control.

Variants can contain virtually any kind of data, including arrays. Since a Variant containing an array provides information about the dimensions of the array, the control can avoid reading or writing “past the end” of the array. This prevents a class of severe and irretrievable crashes (Illegal Page Faults).

The Variant data type is not as familiar to programmers as more common types, such as strings and integers. However, it is very versatile and well suited to passing data to and from the Driver ActiveX control.

OLE provides standard ways to change the type of a Variant, to detect “empty” Variants, and so on. For example, if you pass an “empty” Variant to the Driver’s ReadInputRegisters method, the control will automatically “fill” the Variant with an integer array containing the register values you’ve requested.

Visual Basic supports the Variant type directly; simply Dim a variable As Variant. MFC includes the COleVariant class, which is a simple wrapper of a Variant.

If your programming language supports ActiveX controls (OCXes), it must provide support for the Variant data type. You should consult your language’s documentation for more information.

 For an example of Variant usage, see Sending MODBUS commands

 Back to Contents


User Frame Example

This example is intended to demonstrate two of the MODBUS Driver ActiveX control’s more advanced capabilities, incoming command processing and user command frames.

Note. You do not need to use the Receive or User commands to issue and receive standard MODBUS commands. Use the dedicated methods for this.

For this example, let’s assume that we need to write an application that will let a PC pass information to a large plant-wide control system, such as a Honeywell TDC 3000. The PC will act as an operator terminal that allows plant personnel to change recipe variables for a process.

The PC will maintain a set of recipe variables that can be altered by the program’s operator; the TDC will retrieve these values and use them to operate the process it controls.

Rather than trying to write the recipes into the controller, we’ve decided to let the TDC poll the PC for recipe values at its own convenience. This makes the operator terminal program look like any other device under the TDC’s control.

To do this, we’ll need to accept requests for recipe values from the TDC and send back properly formatted replies. Further, our program should only accept and reply to commands it “understands” that have been sent to its assigned address.

Let’s set some parameters. We’ll say that the PC has the MODBUS address 27, and that the values the TDC will retrieve are “stored” in registers 34040 through 34060. The TDC will be programmed to request these registers from the PC at a regular interval and incorporate the values into the process control logic.

The TDC will use the MODBUS command Read Input Registers (function 4) to retrieve the recipe values from the PC, so we need to “listen” for this command. The Read Input Registers command is formatted as follows in the MODBUS protocol specification:

MODBUS address	1 byte
Function number	1 byte = 4
Starting Register address	1 word
Register count n	1 word
The reply message looks like this:

MODBUS address	1 byte
Function number	1 byte = 4
Byte count	1 byte
Data values	n words
Here’s the code fragment that will handle the data requests from the TDC (click on the highlighted methods to jump to the relevant documentation):

Dim addr As Integer, cmd As Integer, clen As Integer

Dim stat As Integer, startReg As Long

Dim nregs As Integer, n As Integer, subsc As Integer

While Not cancelFlag

DoEvents

stat = MB.Receive(addr, cmd, clen, 100)

'

' See if this is a command we should process

'

If stat = 0 And addr = 27 And cmd = 4 Then

' Retrieve the starting address

MB.ReceiveGetInteger addr

' addr is a signed integer, so convert to a long

' VB has no unsigned 16-bit integer...

If addr >= 0 Then

startReg = addr

Else

startReg = &H10000& + addr

End If

' Read the number of registers requested

MB.ReceiveGetInteger nregs

' Is this a legal register range?

If startReg < 34040 Or startReg + nregs > 34060 Then

' No, send back Error Frame 2, Illegal Data Address

'  Error frame is function number or 80H

MB.UserInit 27, &H80 Or 4

' Error code 2

MB.UserAddByte 2

' Send the code...

If MB.UserSend() <> 0 Then

MsgBox "Error sending error: " + MB.LastErrorString(), _

vbOKOnly or vbExclamation, "Data Poll"

End If

Else

' Request is legal, send data

' Begin by setting up

MB.UserInit 27, 4

' Add byte count

MB.UserAddByte nregs * 2

' Figure out offset into value array

subsc = startReg - 34040

For n = 1 To nregs

' Add a value from the master array

MB.UserAddInteger RegisterValues(subsc)

' Next subscript

subsc = subsc + 1

Next n

' Send the values...

If MB.UserSend() <> 0 Then

MsgBox "Error sending values: " + MB.LastErrorString(), _

vbOKOnly or vbExclamation, "Data Poll"

End If

' Legal register range

End If

' Command we should answer

End If

' "Listening" loop

Wend

This example code fragment makes several assumptions:

•	The variable cancelFlag will be set to True elsewhere in the program when the “listening” loop is to exit.

•	The recipe values are stored in an array called RecipeValues.

•	There is an instance of the MODBUS Driver ActiveX control called MB on the current form.

The code in this example should be fairly easy to understand. Basically, there is a main loop that waits for incoming commands until the cancelFlag variable becomes True. In order to allow the application’s user interface to continue to update, the loop waits only 100 milliseconds (1/10 second) and executes a DoEvents call with every iteration.

If a command is received, the code checks to see if it is addressed to the PC. It also checks to make sure the command is Read Input Registers (the only MODBUS command we are supporting) and that the registers requested fall inside the range that we have values for, that is, 34040 to 34060.

Assuming the incoming command passes all these tests, the code constructs an outgoing reply in the correct format and sends it.

 Back to Contents


Properties

 Pop up Property List

 Go to Methods

 Back to Contents

Here are the MODBUS ActiveX control’s Properties:

Serial Port Parameters

These properties control the operation of the serial port when communicating with the MODBUS device. Changing one of these parameters will affect the next command sent by the control.

Note. There is no way of adjusting the size of the data word; MODBUS RTU mode requires 8 bit words.

BaudRate	Sets or retrieves the communications rate.
CommPort	Sets or retrieves the current communications port.
Parity	Sets or retrieves the current Parity setting.
StopBits	Sets or retrieves the Stop Bits setting
Timeouts

The Timeout properties control when the Driver determines that an incoming MODBUS frame has completed and how long the control will wait for an incoming message to begin.

CharTimeout	Sets or retrieves the character timeout, which tells the Driver when an incoming frame has been completely received.
FrameTimeout	Sets or retrieves the frame timeout, the length of time the Driver waits for an incoming MODBUS message to begin arriving.
Communications Tracing

Communications tracing allows you to track every byte sent or received by the Driver ActiveX control.

TraceEnable	Turn communications tracing on or off.
TraceFile	Specify the output text file that is to receive the communications tracing information.
Other Properties

IOMapping	Sets or retrieves the I/O Mapping mode.
LastError	Retrieves the last error code encountered by the Driver.
LastErrorString	Translate the last error code (or any error code) to a string.


Baud Rate Property

Integer	Property	• Design Time	• Run Time	• Read Only	• Persistent
control.BaudRate = Rate Code

Sets or retrieves the current baud rate used for communications with the MODBUS device. The Rate Code must be one of the integer values below:

Rate Code	Baud Rate
0	110
1	150
2	300
3	600
4	1200
5	2400
6	4800
7	9600
8	19200
9	38400
10	57600
11	115200
 Back to Properties

 Back to Contents


Property Return Type
This is the property's return type. It is also the type used to set new values for the property if that is allowed. Note: "Integer" means "16-bit Integer!"


Design Time Property
This property is available at design time.


Run Time Property
This property is available at runtime.


Persistent Property
The state of this property is stored with the control, so if you change it, the new value will be "remembered" each time that the control is loaded.


Read Only Property
This property only returns a value. You cannot assign a new value to it.


Read-Only Properties
A read-only property cannot have a new value assigned to it. You can only read the value of such properties.


Predefined Constants
If your language supports exported constants (as Visual Basic does), these "variable names" will be pre-defined with the indicated values as soon as you add the MODBUS Driver ActiveX Control to your project.


Char Timeout Property

Long Integer	Property	• Design Time	• Run Time	• Read Only	• Persistent
control.CharTimeout = Timeout in Milliseconds

The MODBUS protocol has no explicit framing, that is, it does not have codes that indicate when a message begins or ends. Instead, the protocol relies on time. Specifically, the protocol says that the end of each message is marked by a “silent” period lasting for at least the length of time required to transmit two and one half characters at the current baud rate.

The CharTimeout property tells the Driver how long it should wait before determining that an incoming message is complete. In most cases, the default value of 50 milliseconds should be adequate.

Note. This is a 32-bit quantity.

However, if you frequently have problems receiving replies from the MODBUS device, or if you are communicating at low baud rates, you may need to increase this value.

Note that the CharTimeout value is only used once an incoming message has started to arrive. The FrameTimeout property determines how long the Driver will wait for an incoming message to begin.

Reducing the CharTimeout value may provide increased throughput if you are trying to sample at the maximum possible rate. However, values below 50 milliseconds may cause erratic operation on some computers.

 See also Frame Timeout

 Back to Properties

 Back to Contents


Comm Port Property

Integer	Property	• Design Time	• Run Time	• Read Only	• Persistent
control.CommPort = Port Number

Sets or retrieves the current port used for communications with the MODBUS device. The port number must be one of the integer values below:

Port Number	Port	Constant
0	COM1	mbdCom_1
1	COM2	mbdCom_2
2	COM3	mbdCom_3
3	COM4	mbdCom_4
4	COM5	mbdCom_5
5	COM6	mbdCom_6
6	COM7	mbdCom_7
7	COM8	mbdCom_8
The number of communications ports supported by your system will vary. Many computers don’t support COM ports beyond number 4.

 Back to Properties

 Back to Contents


Frame Timeout Property

Long Integer	Property	• Design Time	• Run Time	• Read Only	• Persistent
control.FrameTimeout = Timeout in Milliseconds

This property determines how long the control waits for an incoming MODBUS message to begin, either in response to an outgoing command or while “listening” for an incoming command.

When you transmit a MODBUS command using any of the Driver’s command methods, it will wait for a reply to begin arriving for the time specified by the FrameTimeout property. Once the reply begins to arrive, the control uses the CharTimeout property to detect when the incoming message is complete.

If no incoming message begins arriving during the time specified by the FrameTimeout property, the control returns a Timeout Error.

 See also Char Timeout

 Back to Properties

 Back to Contents


I/O Mapping Property

Boolean	Property	• Design Time	• Run Time	• Read Only	• Persistent
control.IOMapping = { True | False }

Normally, the Driver ActiveX control "maps" the Register and Coil addresses that you pass to conform to the Protocol's specifications.  For example, if you refer to Holding Register 40127, the actual binary address transmitted by the Driver will be 126, as defined by the Protocol.

However, if you are not working with Gould equipment, or if you need to control the actual transmitted addresses, you can disable address mapping with this command.

I/O Mapping is enabled by default. To disable it, set the IOMapping property to False.

Important Note. If you disable I/O Mapping, the Driver ActiveX control will perform no address range checking. When I/O Mapping is disabled, you are responsible for supplying register and point addresses exactly as the MODBUS device will receive them.

 Back to Properties

 Back to Contents


Key Port Property

Integer	Property	• Design Time	• Run Time	• Read Only	• Persistent
control.KeyPort = Port Number

For copies of the Driver ActiveX control that are protected by a Hardware Lock, this command changes the printer port that the Driver searches for the hardware key. The default is 0, which selects LPT1. Use one of the port number codes below:

Port Number	Port
0	LPT1
1	LPT2
2	LPT3
The Driver will periodically check for the presence of the Hardware Lock on the port indicated by the KeyPort property. If the key is not found, the Driver will return an error code of -4, “Hardware Key not found.”

Note. This property is not used for OEM versions of the Driver.

 Back to Properties

 Back to Contents


Last Error Property

Integer	Property	• Design Time	• Run Time	• Read Only	• Persistent
IntegerVariable = control.LastError

Retrieves or sets the integer number of the last error reported by the Driver ActiveX control or zero if no error occurred during the last operation.

 Back to Properties

 Back to Contents


Last Error String Property

Integer	Property	• Design Time	• Run Time	• Read Only	• Persistent
StringVariable = control.LastErrorString()
or
StringVariable = control.LastErrorString(errorNumber)

Retrieves the last error reported by the Driver ActiveX control in string format. If you supply the optional argument errorNumber, the Driver will return the string equivalent of the specified error number.

 Back to Properties

 Back to Contents


Parity Property

Integer	Property	• Design Time	• Run Time	• Read Only	• Persistent
control.Parity = Parity Code

This property determines whether any parity bits are used during communications with the MODBUS device. The Parity Code must be one of the values in the table below. The default value of 0 (No Parity) should be used in most situations.

Parity Code	Port Parity	Constant
0	None	mbdParity_None
1	Odd	mbdParity_Odd
2	Even	mbdParity_Even
3	Mark	mbdParity_Mark
4	Space	mbdParity_Space
 Back to Properties

 Back to Contents


Stop Bits Property

Integer	Property	• Design Time	• Run Time	• Read Only	• Persistent
control.StopBits = Stop Bits Code

This property determines the number of stop bits that are used during communications with the MODBUS device. The Stop Bits Code must be one of the values in the table below. The default value of 0 (1 stop bit) should be used in most situations.

Stop Bits Code	Stop Bits	Constant
0	1	mbdStops_1
1	1.5	mbdStops_15
2	2	mbdStops_2
 Back to Properties

 Back to Contents


Trace Enable Property

Boolean	Property	• Design Time	• Run Time	• Read Only	• Persistent
control.TraceEnable = { True | False }

This property enables or disables communications tracing, which is disabled by default.

Communications tracing allows you to see all the data that passes through the communications link in both directions. It can be very useful for diagnosing difficult communications problems.

When communications tracing is enabled, all bytes that are sent and received are recorded to the ASCII text file specified in the TraceFile property. You can enable and disable tracing repeatedly as needed during a session. For example, you can set the TraceEnable property to True just before sending a MODBUS command that isn’t working properly, then set the TraceEnable property back to False before sending other commands.

Note. The TraceFile property must be set to a legal filename before communications tracing will work. Your program must also explicitly set the TraceEnable property to True before tracing will begin; the TraceEnable property is not stored from session to session.

Tip. You can annotate the Trace File contents using the TraceString method.

 See also Trace File Property, TraceString

 Back to Properties

 Back to Contents


Trace File Property

String	Property	• Design Time	• Run Time	• Read Only	• Persistent
control.TraceFile = "Legal filename.txt"

The TraceFile property specifies the output file that the Driver ActiveX control will use to save communications tracing output. Once you have set this file and enabled tracing by setting the TraceEnable property to True, the Driver will “print” every byte that passes through the communications port under its control to the specified file.

Once your program exits, you can examine this file to see what exactly was sent and received for every MODBUS command issued by your program. The file will contain ASCII text in a simple tabular format.

Tip. You can annotate the Trace File contents using the TraceString method.

 See also Trace Enable Property, TraceString

 Back to Properties

 Back to Contents


Property List

BaudRate

CharTimeout

CommPort

FrameTimeout

IOMapping

KeyPort

LastError

LastErrorString

Parity

StopBits

TraceEnable

TraceFile

See also:

Contents

Methods

Error Codes


Methods

 Pop up Method List

 Go to Properties

 Back to Contents

Here are the MODBUS ActiveX control’s Properties:

Important Note. In the method descriptions below, variables that will be modified by the MODBUS Driver ActiveX control appear in red type.

Conversion Functions

Convenience functions for manipulating data:

ArrayToWord	Converts an array of 16 integers to a 16-bit word.
WordToArray	Converts a 16-bit word to a 16-element integer array.
Diagnostics

Detecting the state of the MODBUS device and discovering error conditions:

FetchEventCounter	Retrieves the count of successfully executed MODBUS commands.
FetchEventLog	Retrieves a log of information about all MODBUS transactions.
Loopback	Test communications link and/or retrieve diagnostic information.
ReadExceptionStatus	Retrieves the state of the device’s special status coils.
ReportSlaveID	Determines the slave device’s type and run state.
ReleaseCommPort	Terminates the Driver’s control of any serial port it is currently using.
TraceString	Writes a text annotation to the Communications Tracing file.
Receiving and Interpreting Commands

Accepting MODBUS commands from a remote device:

Receive	Waits for an incoming MODBUS command frame.
ReceiveGetByte	Extract a byte or bytes from the incoming command.
ReceiveGetInteger	Extract an integer or integers from the incoming command.
Reading Values

Obtaining process data from the MODBUS device:

ReadGeneralReference	Read data from “extended memory” files.
ReadInputRegisters	Retrieve values from one or more input registers.
ReadInputStatus	Read the status of discrete inputs.
ReadOutputRegisters	Read values from one or more output (holding) registers.
ReadOutputStatus	Read the status of discrete outputs (coils).
Sending User Commands

Creating and sending commands not directly supported by the MODBUS Driver ActiveX control:

UserAddByte	Adds a byte or bytes to a User command being constructed.
UserAddInteger	Adds an integer or integers to a User command being constructed.
UserInit	Sets up the Driver ActiveX control for transmission of a user command.
UserSend	Transmits a user command frame.
Writing Values

Transmitting values to registers and points on the MODBUS device:

ForceCoil	Writes a value to a single coil.
ForceMultipleCoils	Writes values to a series of consecutive coils.
WriteGeneralReference	Writes data to “extended memory” files
WriteMultipleRegisters	Writes new values to a series of consecutive registers.
WriteRegister	Writes a new value to a single register.


Return type
This is the return type of the method. Note that "Integer" means 16-bit Integer!


Broadcast Mode
Broadcast mode (Address = 0) is allowed for this command.


MODBUS Command
The MODBUS command number that will be sent.


Integer Arrays
Arrays are passed to and from ActiveX controls as Variants. For information on how your development language supports this data type, consult its documentation.


Optional arguments
Optional parameters assume default values if they are not supplied. Languages like Visual Basic permit you to simply omit an optional parameter if it is not needed. Other languages may have different rules.

See also: Optional arguments in C.


Optional arguments in C

C, C++, and C-like languages support “optional” OLE parameters only indirectly. You cannot simply omit an optional parameter and expect the program to work properly.

Technically, optional OLE parameters are passed as const FAR VARIANT &, that is, a reference to a Variant. You must supply a Variant whether you want to use the parameter or not.

To indicate that an optional parameter is omitted, you should set the Variant’s type to VT_EMPTY or VT_ERROR. Officially, Microsoft recommends, “If an optional argument to an Automation method is left blank, do not pass a VARIANT of type VT_EMPTY. Instead, pass a VARIANT of type VT_ERROR with a value of DISP_E_PARAMNOTFOUND (0x80020004L).”

 Back to Methods

 Back to Contents


Array To Word Method

(no return)	Method
control.ArrayToWord Values, Word

Parameter	Type	Usage
Values	Integer Array	Bit values to combine. Must have at least 16 elements.
Word	Integer	Variable to contain combined bits.
Combines the bits in the input array Values into the single 16-bit integer Word. Element 0 of Values becomes bit 0 of Word; element 15 of Values becomes bit 15 of Word.

Note. Any non-zero element of Values will become a 1 in the output word.

 Back to Methods

 Back to Contents


Fetch Event Counter Method

Integer	Method	• Broadcast	Command 11
Status = control.FetchEventCounter(Address, Busy, Events)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command. Use 0 for broadcast mode (addressed to all devices).
Busy	Boolean	Flag indicates that a previous command is still being processed.
Events	Integer	Count of MODBUS commands successfully processed by the device.
Retrieves the MODBUS device’s Busy flag and Event counter. You can use the Event counter to tell when commands have completed successfully. This is a good way to detect when commands that require substantial processing time have finished.

Returns 0 for success or an error code.

 Back to Methods

 Back to Contents


Fetch Event Log Method

Integer	Method	• Broadcast	Command 12
Status = control.FetchEventLog(Address, Busy, EventCt, MsgCt, Log)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command. Use 0 for broadcast mode (addressed to all devices).
Busy	Boolean	Flag indicates that a previous command is still being processed.
EventCt	Integer	Count of MODBUS commands successfully processed by the device.
MsgCt	Integer	Number of events in the Event Log.
Log	Integer Array	Contents of the event log, one byte per element.
Retrieves a MODBUS device’s Event Log. Each entry in the log will occupy one element of the Log array.

The exact meaning of these entries will depend on the device. Usually, but not always, these are byte-wide bitmaps.

Returns 0 for success or an error code.

 Back to Methods

 Back to Contents


Force Coil Method

Integer	Method	• Broadcast	Command 05
Status = control.ForceCoil(Address, Coil, Value)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command. Use 0 for broadcast mode (addressed to all devices).
Coil	Integer	Address of the coil to force (1 – 9999).
Value	Boolean	Value to apply to coil.
Changes an output to a specific value.

Returns 0 for success or an error code.

 Back to Methods

 Back to Contents


Force Multiple Coils Method

Integer	Method	• Broadcast	Command 05
Status = control.ForceMultipleCoils(Address, Start, Count, Values)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command. Use 0 for broadcast mode (addressed to all devices).
Start	Integer	Address of the first coil to force (1 – 9999).
Count	Integer	Number of coils to force.
Values	Integer Array	Values to apply to coils.
Changes a group of outputs to specific values. The new values are supplied to the method packed into 16-bit words. Bit 0 of Values(0) will supply the value for Start; Bit 1 will set Start + 1, and so on. Bit 0 of Values(1) will set Start + 16. The ArrayToWord method can be very handy for building the Values array.

Returns 0 for success or an error code.

 See also ArrayToWord

 Back to Methods

 Back to Contents


Loopback Method

Integer	Method	• Broadcast	Command 08
Status = control.Loopback(Address, DiagCode, Info)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command. Use 0 for broadcast mode (addressed to all devices).
DiagCode	Integer	Code indicating diagnostic to run.
Info	Integer	Parameter value for diagnostic.
Runs a diagnostic on the MODBUS device. The DiagCode parameter specifies which diagnostic to run; the Info parameter may be used by some diagnostic operations and ignored by others. Some diagnostic functions will return information via the Info parameter.

The specific diagnostics available vary from device to device, but diagnostic 0, the Loopback test, is always implemented. This test simply sends back the Info value unchanged.

Returns 0 for success or an error code.

 Back to Methods

 Back to Contents


Read Exception Status Method

Integer	Method	• Broadcast	Command 07
Status = control.ReadExceptionStatus(Address, Value)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command.
Value	Integer	Returns the contents of the Exception register.
Reads the MODBUS device’s Exception register. Depending on the device, this bits in this register may reflect error or status conditions. On Programmable Logic Controllers, this register is usually linked to certain specific special coils.

Returns 0 for success or an error code.

 Back to Methods

 Back to Contents


Read General Reference Method

Integer	Method	• Broadcast	Command 20
Status = control.ReadGeneralReference(Address, RefType, FileNo, Start, Count, Values)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command.
RefType	Integer	The reference type.
FileNo	Integer	The number of the file to read.
Start	Integer	Address of the first register within the file to read.
Count	Integer	Number of registers to read. Limited to 120 or less on most MODBUS devices.
Values	Integer Array	Returns the requested registers.
The Read General Reference command provides a way to retrieve registers in large blocks. It was originally designed to allow access to optional “extended” memory. Contemporary MODBUS devices use this command (and its companion, Write General Reference) for a wide variety of different functions. Consult your device’s documentation for details.

Returns 0 for success or an error code.

 Back to Methods

 Back to Contents


Read Input Registers Method

Integer	Method	• Broadcast	Command 04
Status = control.ReadInputRegisters(Address, Start, Count, Values)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command.
Start	Integer	The first register to read (30001 – 39999).
Count	Integer	Number of registers to read. Limited to 120 or less on most devices.
Values	Integer Array	Returns the requested registers.
Reads the contents of input registers.

Returns 0 for success or an error code.

 For an example, see Sending MODBUS Commands

 Back to Methods

 Back to Contents


Read Input Status Method

Integer	Method	• Broadcast	Command 02
Status = control.ReadInputStatus(Address, Start, Count, Values)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command.
Start	Integer	The first input to read (10001 – 19999).
Count	Integer	Number of inputs to read. Limited to 2000 or less on most devices.
Values	Integer Array	Returns the requested inputs.
Reads the status of discrete inputs. The input states are returned packed into 16-bit integers. Bit 0 (the least significant bit) of Values(0) will contain the state of the input designated by Start; Bit 1 will contain the state of (Start + 1), and so on. You can use the WordToArray method to break the elements of Values into individual bits if that is more convenient.

Returns 0 for success or an error code.

 See also WordToArray

 Back to Methods

 Back to Contents


Read Output Registers Method

Integer	Method	• Broadcast	Command 03
Status = control.ReadOutputRegisters(Address, Start, Count, Values)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command.
Start	Integer	The first register to read (40001 – 49999).
Count	Integer	Number of registers to read. Limited to 120 or less on most devices.
Values	Integer Array	Returns the requested registers.
This command reads the current contents of output (holding) registers.

Returns 0 for success or an error code.

 Back to Methods

 Back to Contents


Read Output Status Method

Integer	Method	• Broadcast	Command 01
Status = control.ReadOutputStatus(Address, Start, Count, Values)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command.
Start	Integer	The first output to read (1 – 9999).
Count	Integer	Number of outputs to read. Limited to 2000 or less on most devices.
Values	Integer Array	Returns the requested outputs.
Reads the status of discrete outputs (coils). The output states are returned packed into 16-bit integers. Bit 0 (the least significant bit) of Values(0) will contain the state of the output designated by Start; Bit 1 will contain the state of (Start + 1), and so on. You can use the WordToArray method to break the elements of Values into individual bits if that is more convenient.

Returns 0 for success or an error code.

 See also WordToArray

 Back to Methods

 Back to Contents


Receive Method

Integer	Method
Status = control.Receive(Address, Command, Length, Wait)

Parameter	Type	Usage
Address	Integer	Returns the address the incoming command was sent to.
Command	Integer	The MODBUS command number in the incoming message.
Length	Integer	Total length in bytes of the incoming command.
Wait	Long Integer	Optional length of time in milliseconds to wait for an incoming command.
•	Intended for advanced users.

This method allows your application to receive commands from other MODBUS devices.

Most applications that use the MODBUS driver will act as “masters.”  They will send commands to MODBUS devices using methods like ReadInputStatus that automatically wait for and process the error and information frame sent back by the “slave” device.

However, you can use the Receive method to cause your application to act as a MODBUS slave. The Receive method waits for a correctly formatted MODBUS command. If such a command arrives, the Receive method will return its MODBUS address, command number, and frame length in the variables listed above. If no MODBUS command arrives within the time allotted, the Receive method will return a Timeout error.

By default, the Receive method waits for the length of time specified in the FrameTimeout property. You can choose another wait interval by specifying the optional Wait parameter.

Important. You do not need to use the Receive method to obtain results from “master” methods like ReadInputStatus. Use this method only if you want to wait for incoming commands from another device or retrieve replies from a User command.

Once a command has arrived, you can check the Address and Command variables to see if your application should process the message. You can use the ReceiveGetByte and ReceiveGetInteger methods to “break” the incoming message into parameters.

If the application needs to send a reply, it can employ the User methods.

Note. If the Receive method successfully captures an incoming frame, the “current position” used by both ReceiveGetByte and ReceiveGetInteger will be set to the first byte of user data in the frame (just after the MODBUS address and command numbers).

Returns 0 for success or an error code.

Receive method Technical Note

When you call the Receive method, the calling thread will block until a command is received or until the allotted timeout elapses. This means no CPU time will be used, but it also means that the thread will not respond to Windows messages. If you use your application’s main thread to call Receive, and use a long timeout value, the application’s user interface won’t update until the Receive method exits.

If your application is going to spend most of its time waiting for incoming commands, you may want to place the code that calls the Receive method on an alternate thread, leaving your application’s main thread to handle GUI updates.

If you are using a language like Visual Basic, which doesn’t directly permit multithreading, you may want to use construct like this:

While control.Receive(Address, Cmd, Length, 100) = mbdError_Timeout

DoEvents

Wend

' Process the incoming command

While this example considerably oversimplifies what would be done in a real application, it gives the idea. This performs a GUI update (uses the VB DoEvents command to process messages) every tenth of a second (the Wait value is 100 milliseconds). That will permit the application to be responsive to the user while continuing to “listen carefully” for incoming MODBUS commands.

A future version of the Driver ActiveX control will support asynchronous notification of incoming MODBUS commands, but this version supports only polled reception.

 See also ReceiveGetByte, ReceiveGetInteger

 See also User Frame Example

 Back to Methods

 Back to Contents


Receive Get Byte Method

(no return)	Method
control.ReceiveGetByte Value, Count, Position

Parameter	Type	Usage
Value	Integer	Returns byte(s) from the incoming message.
Count	Integer	Optional. The number of bytes to retrieve. Defaults to 1.
Position	Integer	Optional. Offset from the beginning of the frame. Defaults to the current position.
•	Intended for advanced users.

Retrieves one or more bytes from an incoming MODBUS message captured by the Receive method.

Note. You must use the Receive method to capture an incoming command frame before using the ReceiveGetByte method. If you call this method with no received frame in memory, the Driver ActiveX control will throw an exception.

The ReceiveGetByte method (and its companion ReceiveGetInteger) allow you to step through a received MODBUS command frame one parameter at a time. By default, if you supply neither a Count nor a Position argument, the ReceiveGetByte method retrieves a single byte from the “current” position and advances the “current” position by one byte.

The “current position” used by both ReceiveGetByte and ReceiveGetInteger starts at the first byte of user data in the frame (just after the MODBUS address and command numbers).

If you supply a Count value greater than 1, Value will be returned as an integer array with one byte from the incoming command in each element. Value(0) will contain the byte at the “current” position, Value(1) the next byte, and so on, until Count bytes have been copied. When the method returns, the “current” position will be increased by Count.

If you want to retrieve bytes from a position other than the “current” position maintained by the Driver, you can supply a Position argument. If you supply this argument, the Driver ActiveX control will begin retrieving bytes at the specified position. When the method returns, the “current” position will point just after the last byte retrieved.

Normally, you will probably want to step through the incoming frame in order, breaking out bytes and integers as needed to understand the command. However, you can override this “stepping” process by supplying a Position argument.

Note. If you supply a Count or Position that would cause the control to try to retrieve data from before the beginning of the frame or after its end, the control will throw an exception.

 See also Receive, ReceiveGetInteger

 See also User Frame Example

 Back to Methods

 Back to Contents


Receive Get Integer Method

(no return)	Method
control.ReceiveGetInteger Value, Count, Position

Parameter	Type	Usage
Value	Integer	Returns integer(s) from the incoming message.
Count	Integer	Optional. The number of integers to retrieve. Defaults to 1.
Position	Integer	Optional. Offset in bytes from the beginning of the received frame. Defaults to the current position.
•	Intended for advanced users.

Operates in exactly the same way as ReceiveGetByte, except (obviously) it extracts integers instead of bytes.

Important Note. This method returns a signed integer. If you are extracting an unsigned integer value, you will need to perform the necessary conversion (usually to a long integer).

 See also Receive, ReceiveGetByte

 See also User Frame Example

 Back to Methods

 Back to Contents


Release Comm Port Method

(no return)	Method
control.ReleaseCommPort

The first time that you invoke a Driver method that requires the use of the serial port, the MODBUS Driver ActiveX control will automatically connect to the port and stay connected. The Driver will normally maintain control of the serial port until the host application ends.

If you need to release the serial port (perhaps so another application can use it) you can invoke the ReleaseCommPort method. This method causes the Driver to immediately terminate its connection to the serial port and free the port.

Note. If you change the port that the Driver is using (via the CommPort property), it will automatically release any connection it is currently maintaining and open the new port on the next method invocation that requires serial port access.

 Back to Methods

 Back to Contents


Report Slave ID Method

Integer	Method	• Broadcast	Command 17
Status = control.ReadOutputRegisters(Address, SlaveID,
RunMode, DDataCount, DeviceData)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command.
SlaveID	Integer	Returns the MODBUS device’s Slave ID.
RunMode	Boolean	Device is running.
DDataCount	Integer	Number of items in the DeviceData array.
DeviceData	Integer Array	Device-dependent status information.
This command reads the MODBUS device’s Slave ID and run state. It also returns an array of device-dependent data, one byte per element.

The meaning of the values in the DeviceData array is completely dependent on the MODBUS device. In some cases, you may need to “assemble” two bytes into a word to get the “actual” value. Consult your device’s documentation for details.

Returns 0 for success or an error code.

 Back to Methods

 Back to Contents


Trace String Method

(no return)	Method
control.TraceString "StringExp"

Parameter	Type	Usage
StringExp	Integer	String to write to trace file.
If you have enabled communications tracing using the TraceEnable and TraceFile properties, you can use the TraceString method to send any arbitrary string to the communications tracing output file. This gives you a way to place “comments” into the trace file so you can identify the command traces.

 See also TraceEnable, TraceFile

 Back to Methods

 Back to Contents


User Add Byte Method

Integer	Method
length = control.UserAddByte(Value, Count)

Parameter	Type	Usage
Value	See below	Byte or bytes to add to user command.
Count	Integer	Optional. Number of bytes to add. Defaults to 1.
•	Intended for advanced users.

This command is used to add bytes to a User command that you are building. These bytes are taken from the Value parameter, which is a Variant. Since Variant parameters can contain a wide variety of data types, the actual type used here depends on your application. You can pass a single byte, a single integer, a byte array, or an integer array.

The Count parameter determines how the Value parameter is interpreted. If Count is 1 or omitted, the Driver will treat Value as a scalar, adding its Least Significant Byte to the frame. If Value is an array, the Driver will add the Least Significant Byte of Value(0) to the user command frame.

If Count is greater than 1, then Value must be an array of integers or bytes. The Driver ActiveX control will add the Least Significant Byte of Count elements of the array to the user command frame.

Returns the new length of the outgoing command frame.

Important Note. You must set up the User command frame with the UserInit method before you can use the UserAddByte method. If you call the UserAddByte method before UserInit, the control will throw an exception.

 See also UserAddInteger, UserInit, and UserSend.

 See also User Frame Example

 Back to Methods

 Back to Contents


User Add Integer Method

Integer	Method
length = control.UserAddInteger(Value, Count)

Parameter	Type	Usage
Value	See below	Integer or integers to add to user command.
Count	Integer	Optional. Number of integers to add. Defaults to 1.
•	Intended for advanced users.

Works in exactly the same way as the UserAddByte method, but adds integers (words). For this method, the Value parameter can contain only a single integer or an integer array.

Returns the new length of the outgoing command frame.

Important Note. You must set up the User command frame with the UserInit method before you can use the UserAddInteger method. If you call the UserAddInteger method before UserInit, the control will throw an exception.

 See also UserAddByte, UserInit, and UserSend.

 See also User Frame Example

 Back to Methods

 Back to Contents


User Init Method

(no return)	Method
length = control.UserInit(Address, Command)

Parameter	Type	Usage
Address	Integer	The address to receive the MODBUS command. Use 0 for broadcast mode.
Command	Integer	The MODBUS command number (0 – 255).
•	Intended for advanced users.

The UserInit method sets up the MODBUS Driver ActiveX control for the construction and transmission of a user command frame. You must call this method before you can call any of the other user command methods, such as UserAddByte, UserAddInteger, and UserSend.

The user command methods allow you to construct MODBUS commands that are not natively supported by the Driver. You may need to use this method if your device requires nonstandard commands, or if you need to reply to an incoming MODBUS command captured with the Receive method.

Calling the UserInit method establishes what MODBUS command you want to send and what address you want to send the command to. After calling UserInit, you can use the UserAddByte and UserAddInteger methods to append data to the end of the command frame, if any additional data is needed. Once the frame is complete, use the UserSend command to transmit it.

Important Note. The user command methods are needed only to transmit MODBUS commands not already supported by the driver. You do not need to call the User methods to use MODBUS protocol commands like Read Input Status. Such commands have their own dedicated methods (e.g., ReadInputStatus).

 See also UserAddByte, UserAddInteger, and UserSend.

 See also User Frame Example

 Back to Methods

 Back to Contents


User Send Method

Integer	Method
Status = control.UserSend()

•	Intended for advanced users.

Sends a user command frame that has been built with the UserInit, UserAddByte, and UserAddInteger commands.

Returns 0 for success or an error code.

Important Note. You must set up the User command frame with the UserInit method before you can use the UserSend method. If you call the UserSend method before UserInit, the control will throw an exception.

Important Note. The UserSend method does NOT wait for a reply from the MODBUS device. It simply transmits the command frame and returns. If you expect a reply from the MODBUS device, and you want to examine this reply, you must capture and interpret it with the Receive method. Note that you can simply choose to ignore any reply if you wish; the MODBUS protocol doesn’t require you to acknowledge incoming frames.

 See also UserInit, UserAddByte, and UserAddInteger

 See also User Frame Example

 Back to Methods

 Back to Contents


Word To Array Method

(no return)	Method
control.WordToArray Word, Values

Parameter	Type	Usage
Word	Integer	The 16-bit integer to break into individual bits.
Values	Integer Array	Returns the bits that make up the source word.
This simple method is the reverse of the ArrayToWord method. It accepts a 16-bit integer and returns a 16-element integer array. Each element of the Values array will contain one bit of the original word. Values(0) will contain the state of Word’s bit 0 (the least significant bit), Values(1) will contain bit 1, and so on.

 Back to Methods

 Back to Contents


Write General Reference Method

Integer	Method	• Broadcast	Command 21
Status = control.WriteGeneralReference(Address, RefType, FileNo, Start, Count, Values)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command.
RefType	Integer	The reference type.
FileNo	Integer	The number of the file to write.
Start	Integer	Address of the first register within the file to write.
Count	Integer	Number of registers to write. Limited to 120 or less on most MODBUS devices.
Values	Integer Array	Contains the data values to write.
The Write General Reference command provides a way to store registers in large blocks. It was originally designed to allow access to optional “extended” memory. Contemporary MODBUS devices use this command (and its companion, Read General Reference) for a wide variety of different functions. Consult your device’s documentation for details.

Returns 0 for success or an error code.

 Back to Methods

 Back to Contents


Write Multiple Registers Method

Integer	Method	• Broadcast	Command 16
Status = control.WriteMultipleRegisters(Address, Start, Count, Values)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command. Use 0 for broadcast mode.
Start	Integer	The first register to write (40001 – 49999).
Count	Integer	Number of registers to write. Limited to 120 or less on most devices.
Values	Integer Array	New values for the registers.
This command writes new values to output (holding) registers.

Returns 0 for success or an error code.

 Back to Methods

 Back to Contents


Write Register Method

Integer	Method	• Broadcast	Command 06
Status = control.WriteRegisters(Address, Register, Value)

Parameter	Type	Usage
Address	Integer	Address of the MODBUS device that is to receive the command. Use 0 for broadcast mode.
Register	Integer	The register to write (40001 – 49999).
Value	Integer	New values for the register.
This command writes a new value to a single output (holding) register.

Returns 0 for success or an error code.

 Back to Methods

 Back to Contents


Method List

ArrayToWord

FetchEventCounter

FetchEventLog

ForceCoil

ForceMultipleCoils

Loopback

ReadExceptionStatus

ReadGeneralReference

ReadInputRegisters

ReadInputStatus

ReadOutputRegisters

ReadOutputStatus

Receive

ReceiveGetByte

ReceiveGetInteger

ReleaseCommPort

ReportSlaveID

TraceString

UserAddByte

UserAddInteger

UserInit

UserSend

WordToArray

WriteGeneralReference

WriteMultipleRegisters

WriteRegister

See also:

Contents

Properties

Error Codes