ModScan

Following is a concise user’s manual for the operation of ModScan32. Operation of the 16-bit version of
ModScan is similar, but is not detailed in this document.

I. Application Overview
A. Document/View Architecture
B. Modbus Data Definition
C. Display Formats
D. Connections

II. Commands
A. File Menu
B. Connection Menu
C. Setup Menu
1. Commands
2. Display Options
3. Extended Options
D. View Menu
1. Commands
2. Config Menu
E. Window Menu
F. Help Menu

III. Toolbars & Status Bar

A. Toolbar
B. Display Selections
C. Status Bar

IV. Testing Features

A. Writing Data to a device
B. Message Counters
C. Observing Serial Traffic
D. Capturing Data
E. User Defined Messages
F. Test Scripts

V. Database Operation

VI. OLE Automation

A. Automation Routines
B. Error Status Codes
C. VBA Example

VII. Custom Displays of Modbus Data

A. Simple Text
B. Discrete Data Values
C. Register Data Values
D. Simple Graphical Items
E. Bar Charts
F. Trend Graphs
G. Dials

29
 ModScan Overview
The ModScan application operates as a MODBUS master device in either RTU or ASCII transmission
modes. ModScan may be used to access and modify data points contained in one or more MODBUS slave
devices connected to the PC via a serial port, modem, or network. ModScan supports the standard
MODBUS message types 01-06, 15 & 16, as well as providing the ability for you to exercise special
features of a slave device by transmitting custom command strings and observing the response. ModScan is
a useful test and diagnostic tool for verifying the proper slave response to MODBUS queries as well as
being a low cost data collection tool for interfacing data into PC database and spreadsheet applications.

Document/View Architecture

ModScan utilizes the standard Windows Multiple-Document-Interface, (MDI), architecture for displaying
modbus data to the user. Each basic ModScan document represents a series, (array), of modbus data points
identified by the following parameters:

Slave Device Address Represents the physical device attached to the modbus network
Data Type Internal data representation, (i.e. input, coil, register)
Data Address Point address within the device
Length Number of points to scan/display

ModScan may also be utilized to represent different types of modbus data using customized graphical
objects as described in section VII.

Associated with each document is also a timer, which is used to periodically scan new data from the defined
slave and refresh the display. The modbus data definition is accessible from the ModScan menu or via edit
controls in the top splitter window of the document display. As new data is obtained from the slave device,
it is written to the bottom splitter window in one of several formats, depending upon your preference. The
size of each document display window is adjustable via the splitter control.

Modbus Data Definition

The upper half of each Document’s View represents the data selected for display, (and possible capture to a
historical data file). In most testing applications, the ModScan will only be connected to a single modbus
slave device, however, in a multidrop modbus network, there may be several devices accessible from a
single connection. The “Device Id” edit control allows you to specify the slave address for the source of the
data. Likewise, edit controls are available to select the point type, data address, and number of data points
to access.

Notice that the modbus protocol uses a 5-digit representation for the slave data address which infers the
point-type. For example, INPUT STATUS values are always represented in the range 10001-19999:
HOLDING REGISTERS are displayed as 40000-49999. The ModScan application uses the standard
notation for displaying data in the bottom splitter window, however the address specified in the upper
splitter address edit control assumes a 4-digit physical point address. This address, coupled with the point-
type specifier completely defines the data to be accessed in the slave device.

The upper splitter window also contains two counters which are used to tally the number of data requests
made from this document to the modbus connection and the number of valid slave responses received in
reply. A button is available within the display which resets the counters associated with this document.

30
 Display Formats

As data is received from the slave device, it is displayed to the lower splitter view of the associated
document. Any errors incurred during the exchange of information will be displayed on the first line. The
font and colors used to display the data is configurable via the View, Config menu options.

Modbus register data may be displayed in any of the following formats:

Binary Data displayed as 16 discrete values.

Decimal Ranges from -32767 to 32768
Hexadecimal 0000-ffff
Floating-Point IEEE Standard Floating Point Notation
(Requires two registers per value)
Swapped Floating Inverted Floating Point used by some processors
Point
Double Precision 64-bit Floating Point Notation
Floating Point
Swapped Double Inverted 64-bit Float Values

Connections

ModScan may be used to obtain data from modbus slave device connected to the PC in one of three basic
physical arrangements. The most common connection is via any one of the four available PC serial COM
ports. ModScan uses the standard Win32 software drivers for communication with the COM ports, thereby
providing support for any hardware serial boards which may be installed in the Windows operating system,
(including RS-232, RS-485, etc.). You have complete control over the operating characteristics of the serial
connection by selecting the appropriate baud rate, parity, and control line, (handshaking), properties to
match the slave device(s).

In remote testing situations, the ModScan application may be used to communicate with a modbus network
over a dedicated modem connection. ModScan supports the TAPI, (telephony application interface),
standard implemented in Windows and Windows NT. If selected, the modem connection dialog allows you
to enter a phone number for dialing. Any TAPI device configured within the Windows operating system is
available for use.

ModScan allows modbus communications to occur over a TCP/IP network using the modbus/TCP protocol.
ModScan operates as a modbus/TCP client application, (modbus master), accessing data from any
connected modbus/TCP server. Several vendors now offer direct TCP/IP networking support for mobus
devices and ModScan is an excellent way to access/test these devices. You may also use one of several
available modbus to TCP/IP bridge devices which can service network requests to a connected serial port.
A bridge device operates as a network server, providing support to numerous client applications distributed
over the network and interfacing modbus requests for data to slave devices connected serially. WinTECH
Software provides such a server, (MNetSvr), as an application which runs under Windows.

It is also possible to connect via modem to a remote system utilizing the built-in networking characteristics
of Windows ‘95 & NT. To do this, you will need to configure the ModScan application to connect via a
TCP/IP connection which has been setup within Windows to automatically dial and establish a PPP
connection with another Windows machine which is connected directly to the slave device(s) you wish to
use. In this case, ModScan operates as if it were using a network card connected directly to a modbus to
TCP/IP bridge device.

ModScan Commands
31
 File Menu

The File menu offers the following commands:

New Creates a new document. Use this command to create a new document in ModScan.
Each document represents a different block of data from a modbus device.

Open Opens an existing document. Use this command to open an existing document in a new
window. You can open multiple documents at once. Use the Window menu to switch
among the multiple open documents.

Custom This command allows you to open/create a Custom Display document. Using a
customized document, you can drag & drop modbus data points from various slave
devices onto your display to be shown in a variety of graphical formats.

Close Closes an opened document. Use this command to close the active document. If the data
definition, (address, point type, etc), has changed since the document was opened,
ModScan suggests that you save changes before you close it. If you close a document
without saving, you lose all changes made since the last time you saved it. Before
closing an untitled document, ModScan displays the Save As Dialog and suggests that
you name and save the document. You can also close a document by using the Close
icon on the document's window.

Save Saves an opened document using the same file name. Use this command to save the
active document to its current name and directory. When you save a document for the
first time, ModScan displays the Save As dialog box so you can name your document.

Save As Saves an opened document to a specified file name. Use this command to save and name
the active document. ModScan displays Save As dialog box the so you can name your
document.

Print Prints a document.

Printer Setup Selects a printer and printer connection.

Exit Exits ModScan32.

32
 Connection Menu

The Connect menu offers the following commands:

Connect Attaches the ModScan application to a modbus network, enabling data collection. Use
this command to connect the ModScan application to a modbus network. A dialog box
will prompt you for information relative to the connection. You may use ModScan to
connect directly to a modbus device via one of four Windows COM ports, or via a
modem or TCP/IP network. The possible ways to connect are presented in the drop-
down list contained within the connect dialog box.
If you select a direct connection, you must specify the associated baud rate, parity and
control line selections which match your modbus devices. If a modem connection is
selected, you must supply the dialing number and if a network selection is made, you
must supply the necessary IP address for the connection.
The protocol selections button allows to specify either the modbus RTU or ASCII
transmission mode and the time-out associated with the expected slave response to a
query.

Disconnect Detaches the ModScan application from the network, freeing up resources for other
Windows applications.

Setup Menu

The Setup menu offers the following commands:

Data Definition Defines the document properties of the modbus data to be scanned. Use this
command to define the characteristics of the data to be monitored for the active
document. You may select up to 128 data points for display.

Display Options Allows the document data to be viewed in a variety of formats.

Extended Options Provides the ability to write data to a connected slave device.

Text Capture Begins collecting modbus data to a specified text file. Use this command to store
the results of each modbus query to an ASCII text file. Data is written to the
specified file, (one scan per line), in the format selected for display in the lower
splitter view, (i.e. decimal, hex, float). If an error was encountered during the
polling transaction, the error message will be logged to the file rather than the
data. There is no “wrap-around” feature for collecting data. New data is
appended to the file on each query and the file can become very large vary fast if
used with a short scan frequency.

Dbase Capture Begins collecting data into a defined database table. The ability to save modbus
data directly to a database is an optional feature of ModScan. If the feature is
unavailable, the Database Capture menu selection will be grayed out and not
accessible. If enabled, this command allows you to store the results of each query
into an active Microsoft compatible database for interfacing modbus data with
custom designs.

Capture Off Stops data collection. Use this command to stop the document from updating the
capture file.

Reset Counters Clears all modbus message status counters in all documents. Use this command to
reset the modbus message counters for all active documents.

33
 Display Options

The Display Options menu offers the following commands:

Show Data This default view configuration displays data values as obtained from the modbus
slave device. ModScan is normally configured to display modbus data points in
the lower splitter view of the associated document. Data points are displayed in
order from top to bottom, left to right. Data is displayed using the current colors
and font selection. Coil values are displayed as either <0> or <1>. Register
values may be displayed in a variety of formats according to your preferences.

Show Traffic This option allows the serial data stream to be displayed in place of the data
points. Use this command to troubleshoot the connection to a particular modbus
device. When selected, this option will display the serial data exchanged
between the ModScan application and the slave device associated with this
document. The data display splitter view will show data transmitted to the slave
device and data returned from the slave device as communications occur during
the normal polling cycle. This will help to isolate a problem with possible
misinterpretation of the modbus protocol. Data will be displayed in either
decimal or hex, depending upon the preference settings in effect for viewing the
modbus data points. Normal data collection, (if enabled), will continue.

Binary Register values are displayed as 16 discrete bits. Use this command to display the
contents of modbus registers as a group of 16 discrete values as shown below:
41000: <0001000100110100>
This example shows the HOLDING REGISTER located at address 1000 to
contain the value 1134H.

Decimal Register values are displayed in decimal format, (-32767-32768).

Hex Register Values are displayed in Hexadecimal, (0000-ffff).

Floating Point Register Values are displayed in floating point notation, (two registers are
required). Use this command to display the contents of modbus registers as
floating point values based on interpretation of two consecutive registers, (32-
bits), according to the IEEE specification. ModScan will attempt to convert the
values contained within the selected registers as the IEEE value. If the bit pattern
contained within the register set matches the criteria for a floating point number,
the value will be displayed on the lower document splitter view as a decimal
value associated with the first register address of the pair.

Swapped FP Register Values are displayed in floating point notation, (least significant register
first). Use this command to display the contents of modbus registers as floating
point values based on interpretation of two consecutive registers, (32-bits),
according to the IEEE specification. ModScan will attempt to convert the values
contained within the selected registers as the IEEE value. If the bit pattern
contained within the register set matches the criteria for a floating point number,
the value will be displayed on the lower document splitter view as a decimal
value associated with the first register address of the pair. The difference
between this option and the normal Floating Pt display option is the order of the
registers with respect to the IEEE standard.

Dbl Float Register Values are displayed in floating point notation, (four registers, (64 bits),
are required). Use this command to display the contents of modbus registers as
floating point values based on interpretation of four consecutive registers, (64-
bits), according to the IEEE specification for double-precision numbers.
34
 ModScan will attempt to convert the values contained within the selected
registers as the IEEE value. If the bit pattern contained within the register set
matches the criteria for a floating point number, the value will be displayed on
the lower document splitter view as a decimal value associated with the first
register address of the pair.

Swapped Dbl Register Values are displayed in floating point notation, (least significant register
first). Use this command to display the contents of modbus registers as floating
point values based on interpretation of four consecutive registers, (64-bits),
according to the IEEE specification for double-precision numbers.
ModScan will attempt to convert the values contained within the selected
registers as the IEEE value. If the bit pattern contained within the register set
matches the criteria for a floating point number, the value will be displayed on
the lower document splitter view as a decimal value associated with the first
register address of the pair. . The difference between this option and the normal
Floating Pt display option is the order of the registers with respect to the IEEE
standard.

Hex Addresses Displays the addresses of data points in hexadecimal notation. Use this command
to display the addresses associated with a modbus data point in hexadecimal
notation rather than decimal.

35
 Extended Options

The Setup Extended Options menu offers the following commands:

Force Coils Provides the ability to write coil values to a designated slave device. Use this
command to manually force a group of coils to a given state, (on/off). The
ability to address multiple coils in a
slave depends upon the operating characteristics of the device. ModScan uses
modbus message 15, (Force Multiple Coils), to transmit the request to the
designated slave. Selecting this menu option will initiate a dialog box which
prompts for the address of the data to write:
Entering appropriate values for the slave address, point address, and number of
coils to write initiates a second dialog which allows you to manually select the
value for each coil. Use the radio buttons to select either ON of OFF for each
coil value. The scrollbar control allows you to advance to the next series of coil
addresses:

Preset Registers Provides the ability to write register values to a designated slave device. Use this
command to force a group of holding registers to selected values. ModScan
uses modbus message 16, (Preset Registers), to write data to the designated
slave device. Selecting this menu option will initiate a dialog box which prompts
for the address of the data to write:
Entering appropriate values for the slave address, point address, and number of
registers to write initiates a second dialog which allows you to manually select
the value for each register. Use the edit controls associated with each register
address to enter its value. Values may be entered in either decimal or
hexadecimal notation, depending upon the preference selected for modbus data
display. The scrollbar control allows you to advance to the next series of
register addresses up to the maximum specified in the previous dialog:
Buttons at the right of the Preset Registers dialog allow you to configure a series
of register values and write them to a disk file for later retrieval and
downloading to a modbus slave. Pressing the To File button saves the currently
defined register values to a selected file. The From File button fills the edit
controls of the dialog with values obtained from a previously saved disk file.

User Commands Allows you to define and transmit a custom command. Use this command to
customize a command string for transmission to a designated modbus slave
device. This command is useful for observing the slave response to non-
standard modbus queries or to test its reaction to requests for data which may
not be available. The slave device should respond with the proper exception
message if a master device asks for data which is beyond its address range or
otherwise unavailable via the modbus. After transmitting the user string,
ModScan will receive characters for the entire time-out period specified for the
connection. The results will then be updated to the appropriate edit control on
the dialog box. User defined messages transmitted to a slave device will not
show up in the ModScan message counters.

Mask Write This menu selection provides support for the modbus Write-Mask function,
(command 22), which allows you to specify a bit pattern to be used in updating
the contents of a holding register.

Script Files Begins execution of a test script.

View Menu

36
The View menu offers the following commands:

Toolbar Shows or hides the toolbar.

Status Bar Shows or hides the status bar.

Display Bar Shows or hides the format toolbar used to select the display format for
modbus registers.

Config Allows you to customize the appearance of ModScan by selecting the

colors and font used.

Config Menu

The config options supported under the View menu offers you the ability to select the colors used to display
modbus data as well as the character font.

Background Color Selects the color for the ModScan data display splitter view.

Foreground Color Selects the text color used to display data values.

Status Color Selects the color used to show the modbus status line.

Font Selects the font.

Window Menu

The Window menu offers the following commands, which enable you to arrange multiple views of multiple
documents in the application window:

Cascade Arranges windows in an overlapped fashion.

Tile Arranges windows in non-overlapped tiles.

Arrange Icons Arranges icons of closed windows.

Window 1,2... Goes to specified window.

Help Menu

The Help menu offers the following commands, which provide you assistance with this application:

Help Topics Offers you an index to topics on which you can get help.

About Displays the version number of this application.

37
 Tollbars & Status Bar
Toolbar

The toolbar is displayed across the top of the application window, below the menu bar. The toolbar
provides quick mouse access to many tools used in ModScan. The toolbar is detachable and dockable by
clicking the mouse on the toolbar background and dragging it to the desired location within the ModScan
application window.

To hide or display the Toolbar, choose Toolbar from the View menu (ALT, V, T).

Toolbar buttons, (from left to right), allow you to:

Open a new document.

Open an existing document. ModScan displays the Open dialog box, in which you can locate
and open the desired file.

Save the active document or template with its current name. If you have not named the
document, ModScan displays the Save As dialog box.

Define the characteristics of the modbus data to be displayed.

Show modbus data points in lower splitter view.

Show serial data streams in lower splitter view.

Print the active document.

Display the About Box.

Context Help.

Display Selection Toolbar

The format toolbar is displayed across the top of the application window, below the menu bar. The format
toolbar provides quick mouse access to select the format used by ModScan to display the contents of
modbus registers. The toolbar is detachable and dockable by clicking the mouse on the toolbar background
and dragging it to the desired location within the ModScan application window.

Toolbar buttons, (from left to right), allow you to:

Display registers in binary.

Display registers in decimal.

Display registers in hexadecimal.

Display registers in floating-point notation.

Display registers in floating-point notation, (interpreted as having the least significant 16-bits
in the first register).

Display registers in 64-bit double precision floating point notation.

38
 Display registers in double-precision floating point, (interpreted as having the least significant
16-bits in the first register).

Status Bar

The status bar is displayed at the bottom of the ModScan window. To display or hide the status bar, use the
Status Bar command in the View menu.

The left area of the status bar describes actions of menu items as you use the arrow keys to navigate through
menus. This area similarly shows messages that describe the actions of toolbar buttons as you depress
them, before releasing them. If after viewing the description of the toolbar button command you wish not to
execute the command, then release the mouse button while the pointer is off the toolbar button.

The right areas of the status bar indicate the message counters for all modbus message activity logged by
the various active documents.

39
 Testing Features
Writing Data

In order to write a MODBUS data point in a slave device, the communications with the device must first be
initiated by scanning a series of data points by configuring the correct addressing information and initiating
a polling cycle. Once the data is successfully displayed, double-clicking the address/value portion of the
screen will initiate a dialog box which allows the value to be changed. If the polling cycle has been
configured to represent coil addresses, double-clicking an address will initiate the Change Coil Dialog:

The Change Register Dialog Box may be initiated by configuring the display to represent register data and
double clicking on an address:

Register values may be written using binary, decimal, hexadecimal, or floating-point notation, depending on
the preference selection currently in effect.

Pressing the Update Button in either write data point dialog will initiate the appropriate MODBUS write
command, (05 or 06), during the next scheduled poll.

Message Counters

Each document maintains a counter for each query message transmitted to a modbus slave device and a
counter for each correct response returned from the addresses slave. The counters for a given document
may be reset via a button control accessible via the upper, (data definition), splitter view. A total count of
all message counters from all active documents, (including any OLE Automation client documents), is
displayed via the ModScan status bar.

Viewing Serial Traffic

Use this command to troubleshoot the connection to a particular modbus device. When selected, this option
will display the serial data exchanged between the ModScan application and the slave device associated
with this document. The data display splitter view will show data transmitted to the slave device and data
returned from the slave device as communications occur during the normal polling cycle. This will help to
isolate a problem with possible misinterpretation of the modbus protocol. Data will be displayed in either
decimal or hex, depending upon the preference settings in effect for viewing the modbus data points.
Normal data collection, (if enabled), will continue.

Capturing Data

Use this command to store the results of each modbus query to an ASCII text file. Data is written to the
specified file, (one scan per line), in the format selected for display in the lower splitter view, (i.e. decimal,
hex, float). If an error was encountered during the polling transaction, the error message will be logged to
the file rather than the data. There is no “wrap-around” feature for collecting data. New data is appended
to the file on each query and the file can become very large vary fast if used with a short scan frequency.
The ability to save modbus data directly to a database is an optional feature of ModScan. If the feature is
unavailable, the Database Capture menu selection will be grayed out and not accessible. If enabled, this
command allows you to store the results of each query into an active Microsoft compatible database for
interfacing modbus data with custom designs.

40
 User Defined Messsages

Use this command to customize a command string for transmission to a designated modbus slave device.
This command is useful for observing the slave response to non-standard modbus queries or to test its
reaction to requests for data which may not be available. The slave device should respond with the proper
exception message if a master device asks for data which is beyond its address range or otherwise
unavailable via the modbus.

After transmitting the user string, ModScan will receive characters for the entire time-out period specified
for the connection. The results will then be updated to the appropriate edit control on the dialog box. User
defined messages transmitted to a slave device will not show up in the ModScan message counters.

Scripts

Test scripts consist of ASCII text data field separated by commas. They may be constructed using any word
processor or spreadsheet application. A test script entry consists of at least 7 data fields as depicted in the
following example script, (example.csv).

//
// Example Test Script for ModScan Application
//
// Each Script entry consists of the following
// comma delimited data fields:
//
// TEST NAME, NODE, FUNCTION, ADDRESS, LENGTH, DATA, CONTROL CODE
//
// Double slashes on the front of a line denote comments
//
// The following Control Codes may be used (i.e. last field on each line)
// \ -- Continue DATA fields on next line
// C -- Generate Bad CRC message to slave
// D -- Check response data quantity only, (ignore actual data)
// 1 -- Expect Exception Response 01
// 2 -- Expect Exception Response 02
// 4 -- Expect Exception Response 04
// R -- Expect no Response
// T (default) -- Verify Response Data
//
//
// First Test:
// Write 20 Coils to Node 1 starting at address 100
// Data is alternating pattern of ones & zeros
// (DATA field consists of 32-bits and may be specified
// as a decimal, hex or floating-point value)
//
Preset Multiple Coils,1,15,100,20,0xAAAAA,T
//
//
// Second Test:
// Verify results of first test by reading the pattern back
//
Verify Coil Status,1,1,100,20,0xAAAAA,T
//
// Third Test:
// Read 100 Input Status values
41
// ignore the data and only verify proper quantity returned
//
Verify Input Status,1,2,100,100,0,D
//
//
// Forth Test:
// Check Slave Response to request for 1000 registers
// (Should probably generate an exception response)
//
Test Exception 2,1,3,100,1000,0,2
//
// Fifth Test:
// Check Slave Response to bad CRC
//
Invalid Request,1,1,100,1,0,C
//
// Sixth Test:
// Query an unknown device & expect no response
//
Query Device 73,73,1,1,1,0,R
//
// Seventh Test:
// Write 6 Holding Registers with data
// (Each floating point number represents
// two registers -- The NAME field on the
// continuation line is ignored)
//
Write Floats,1,16,100,6,1.00,\
,2.00,3.00,,,,T
//
// Eighth Test:
// Verify Test Seven by reading back the Registers
//
Read Floats,1,3,100,6,1.00,\
,2.00,3.00,,,,T
//
// END OF SCRIPT
end

42
 Database Operation
An optional feature of ModScan32 allows you to write data directly into a Microsoft compatible database
such as Access. ModScan uses the Jet database engine to provide an efficient exchange of information from
an addressed slave device into the designated database table. Selecting the Dbase Capture menu item
allows you to associate a ModScan document with a given database table. The table will then be updated
with new data each time the slave device is polled. If you change the properties of the document while
collection is enabled, updates to the database will temporarily cease. Database updates will resume if the
original properties are restored.

ModScan attempts to write the modbus data associated with a particular document as a linear table
consisting of the time, status code, and value for each defined point. The table is created with the number
of columns equal to the number of points selected in the active document plus two additional fields to
contain the time & date and the status code associated with each reading. Table headers to identify each
column consist of the 5-digit modbus address for each data point. For example, a table defined to contain 5
input registers beginning at address 44 would look like:

Time Status 30044 30045 30046 30047 30048

11/5/97 12:53 P.M. 0 0000 0001 0002 0003 0004
11/5/97 12:54 P.M. 0 0000 0001 0002 0003 0004
11/5/97 12:55 P.M. 0 0000 0001 0002 0003 0004

43
 OLE Automation

An optional feature of ModScan32 is the ability to access modbus data using OLE Automation routines.
This allows custom programs to be generated, (using Visual Basic, Excel Basic, etc.,), to interpret and
format data according to your specific requirements. OLE Automation routines provide both read and write
access to one or more modbus slave devices through the ModScan application.

Using the OLE Automation routines is a very simple process:

The VBA application links to the ModScan32.tlb file, (Type Library), which details the names for each
automation procedure and its argument list. From the Visual Basic development framework, this is done by
selecting the menu item to include a custom type library and then browsing for ModScan32.tlb. During the
initial Form Load operation, the application must call Create Object as follows:

CreateObject("ModScan32.Document")

The application then creates one or more PollRequests which define an array of data points to be read from
a modbus device. Data defined by the Poll Request will be automatically scanned by the ModScan
application on a 1 second basis. (NOTE: The ModScan application must be connected to the modbus
network prior to the VBA application starting up.)

The application uses the handle returned from the CreatePollRequest procedure to access, (read or write), a
value within the defined array.

During application termination, it must free the memory used by the ModScan application to maintain the
data points by deleting any Poll Requests created.

Refer to the Visual Basic Example application included with the ModScan distribution files for additional
details.

OLE Automation Routines

The following OLE Automation routines are supported by ModScan32:

short CreatePollRequest (short Device, long Address, short Length)

Arguments:
Device - Specifies the slave device address
Address - Specifies the data point address,(in modbus master (5 digit) format.
coil status addresses: 00000-09999
input status addresses: 10000-19999
input register addresses: 30000-39999
holding register addresses: 40000-49999
Length - Specifies the number of values included in the definition
Return Value:
Point Handle - Defines the array structure for future reads & writes
Notes:
Sets up data structures within ModScan to begin polling the specified data. ModScan must be
connected to the modbus network prior to creating the data array. CreatePollRequest returns a
non-zero value if the data structure was successfully created, otherwise it returns 0.

short ReadValue (short PointHandle, short Index, short *pValue)

Arguments:
Point Handle - refers to value returned from CreatePollRequest
Index - Specifies the index into the array structure
*pValue - is a pointer to a value to be returned.
Return Value:
44
 Status - indicates whether or not the operation was completed successfully
Notes:
Status will be MBUS_OK, (0), if the data point was successfully read, otherwise, a non-zero value
indicates one of the defined error conditions.

short WriteValue (short PointHandle, short Index, short Value)

Arguments:
Point Handle - refers to value returned from CreatePollRequest
Index - Specifies the index into the array structure
Value - is the data to be written.
Return Value:
Status - indicates whether or not the operation was completed successfully
Notes:
Status will be MBUS_OK, (0), if the data point was successfully queued for transmission to the
addresses slave. A zero return value does not indicate successful transmission of the request to the
slave device. The controlling application is responsible for verifying the write operation by
reading back the value written.

short ModifyPollRequest (short PointHandle, short Device, long Address, short Length)
Arguments:
Point Handle - refers to value returned from CreatePollRequest
Device - Specifies the new slave device address
Address - Specifies the new data point address,(in modbus master (5 digit) format.
Length - Specifies the number of values included in the definition
Return Value:
Status will be MBUS_OK, (0), if the data point was successfully modified, otherwise, a non-zero
value indicates one of the defined error conditions.
Notes:
Immediately after changing the parameters of a defined data point, the current status of each value
in the array will be set to MBUS_UNINITIALIZED, indicating that the data does not represent
that defined by the device/address definition. The first poll after modification should reflect the
true status of the addressed data array.

short DeletePollRequest (short PointHandle)

Arguments:
Point Handle - refers to value returned from CreatePollRequest
Return Value:
Status will be MBUS_OK, (0), if the data point was successfully modified, otherwise, a non-zero
value indicates one of the defined error conditions.
Notes:
This routine frees up memory allocated by ModScan to support the defined Poll Request.

45
 ModScan OLE Automation Error Return Values

The following status codes may be returned from the ModScan application in response to an OLE
Automation request:

1-255 Modbus Exception Message as returned from slave device.

256 Invalid Data Point Handle
257 reserved
258 Invalid Data Point Address
259 reserved
260 reserved
261 reserved
262 Out-Of-Memory
263 Time-Out, (Data not received from slave)
264 reserved
265 Invalid checksum in response from slave
266 ModScan not connected to modbus network
267 reserved
268 reserved
269 Remote TCP/IP Server not connected
270 Data Uninitialized, (Values not valid)
271 ModScan Demo Time Expired

46
 Visual Basic Example

The example Visual Basic application included with the ModScan32 distribution files is a simple take-off
on the ModScan application itself. The Form creates four array points, (one each for inputs, coils, input
registers, and holding registers). A timer is used to read and update the data once per second. Edit controls
are used to define the addresses as shown below:

Code for the example follows:

Public m_svr As IModSca

Dim PollHandle(4) As Integer ‘Handle for each of the four array points
Dim status(4) As Integer ‘Status return value for each ReadValue request
Dim SlaveDevice As Integer ‘All points use same slave address
Dim StartAddress(4) As Long ‘starting address for each array

Dim Modbus_Id(4) As Long ‘ prefix for selected address

Dim Counter As Integer
Dim temp As Integer
Dim Modbus_Addr As Long ‘qualified 5-digit modbus address

Private Sub coiladdress_Change()

‘
‘ User has changed address for coil array
‘ recalculate 5-digit modbus address
‘ and ModifyPollRequest accordingly
‘
If (IsNumeric(coiladdress.Text)) Then
StartAddress(1) = coiladdress.Text
Modbus_Addr = Modbus_Id(1) + StartAddress(1)
status(1) = m_svr.ModifyPollRequest(PollHandle(1), SlaveDevice, Modbus_Addr, 10)
StatusMsg (status(1))
End If

End Sub

Private Sub Device_Change()

‘
‘ User has changed slave device
‘ Modify all four PollRequests
‘
If (IsNumeric(Device.Text)) Then
SlaveDevice = Device.Text

Modbus_Addr = Modbus_Id(0) + StartAddress(0)

temp = m_svr.ModifyPollRequest(PollHandle(0), SlaveDevice, Modbus_Addr, 10)

Modbus_Addr = Modbus_Id(1) + StartAddress(1)

temp = m_svr.ModifyPollRequest(PollHandle(1), SlaveDevice, Modbus_Addr, 10)

Modbus_Addr = Modbus_Id(2) + StartAddress(2)

temp = m_svr.ModifyPollRequest(PollHandle(2), SlaveDevice, Modbus_Addr, 10)

47
 Modbus_Addr = Modbus_Id(3) + StartAddress(3)
temp = m_svr.ModifyPollRequest(PollHandle(3), SlaveDevice, Modbus_Addr, 10)
End If

End Sub

Private Sub Form_Load()

‘
‘ Create the ModScan interface object
‘
Set m_svr = CreateObject("ModScan32.Document")

Modbus_Id(0) = 10000 'input status prefix

Modbus_Id(1) = 0 'coil status prefix
Modbus_Id(2) = 30000 'input register prefix
Modbus_Id(3) = 40000 'holding register prefix

‘
‘ create the four PollRequests using
‘ default values
‘
SlaveDevice = 1
For Counter = 0 To 3
StartAddress(Counter) = 1
Modbus_Addr = Modbus_Id(Counter) + StartAddress(Counter)
PollHandle(Counter) = m_svr.CreatePollRequest(SlaveDevice, Modbus_Addr, 10)
Next Counter

statusline = "** UNINITIALIZED **"

End Sub

Private Sub Form_Terminate()

‘
‘ Free allocated resources
‘
For Counter = 0 To 4
m_svr.DeletePollRequest (PollHandle(Counter))
Next Counter

End Sub

Public Sub StatusMsg(Index As Integer)

‘
‘ Generate text status message
‘
If Index = 0 Then statusline = ""
If Index > 0 And Index < 256 Then statusline = "Slave Device Exception Response"
If Index = 256 Then statusline = "Invalid Handle"
If Index = 257 Then statusline = "Modbus Message Overrun"
If Index = 258 Then statusline = "Invalid Address"
48
If Index = 259 Then statusline = "Invalid Device Address"
If Index = 260 Then statusline = "Invalid Length Specification"
If Index = 261 Then statusline = "Invalid modbus command"
If Index = 262 Then statusline = "Driver Out-Of-Memory"
If Index = 263 Then statusline = "** Time-Out **"
If Index = 264 Then statusline = "Invalid Protocol Specification"
If Index = 265 Then statusline = "** Bad Checksum **"
If Index = 266 Then statusline = "Server NOT Connected"
If Index = 267 Then statusline = "Invalid Response from Driver"
If Index = 268 Then statusline = "Modbus Write Failure"
If Index = 269 Then statusline = "Remote Server not Connected"
If Index = 270 Then statusline = "** UNINITIALIZED **"
If Index = 271 Then statusline = "ModScan Demo Time Expired"

End Sub

Private Sub holdingregsaddress_Change()

‘
‘ User has changed address for holding registeres
‘
If (IsNumeric(holdingregsaddress.Text)) Then
StartAddress(3) = holdingregsaddress.Text
Modbus_Addr = Modbus_Id(3) + StartAddress(3)
status(3) = m_svr.ModifyPollRequest(PollHandle(3), SlaveDevice, Modbus_Addr, 10)
StatusMsg (status(3))
End If

End Sub

Private Sub inputaddress_Change()

‘
‘ User has changed starting address for
‘ input status points
‘
If (IsNumeric(inputaddress.Text)) Then
StartAddress(0) = inputaddress.Text
Modbus_Addr = Modbus_Id(0) + StartAddress(0)
status(0) = m_svr.ModifyPollRequest(PollHandle(0), SlaveDevice, Modbus_Addr, 10)
StatusMsg (status(0))
End If

End Sub

Private Sub inregsaddress_Change()

‘
‘ User has changed input register address
‘
If (IsNumeric(inregsaddress.Text)) Then
StartAddress(2) = inregsaddress.Text
Modbus_Addr = Modbus_Id(2) + StartAddress(2)
status(2) = m_svr.ModifyPollRequest(PollHandle(2), SlaveDevice, Modbus_Addr, 10)
StatusMsg (status(2))
End If

End Sub

Private Sub Timer1_Timer()

49
‘
‘ Each secon read and update all 10 values
‘ in each of th efour arrays
‘
For Counter = 0 To 9
status(0) = m_svr.ReadValue(PollHandle(0), Counter, temp)
StatusMsg (status(0))
If temp = 0 Then
inputstatus(Counter).Value = 0
Else
inputstatus(Counter).Value = 1
End If
Next Counter

For Counter = 0 To 9
status(1) = m_svr.ReadValue(PollHandle(1), Counter, temp)
StatusMsg (status(1))
If temp = 0 Then
coilstatus(Counter).Value = 0
Else
coilstatus(Counter).Value = 1
End If
Next Counter

For Counter = 0 To 9
status(2) = m_svr.ReadValue(PollHandle(2), Counter, temp)
StatusMsg (status(2))
inputreg(Counter).Caption = temp
Next Counter

For Counter = 0 To 9
status(3) = m_svr.ReadValue(PollHandle(3), Counter, temp)
StatusMsg (status(3))
holdingreg(Counter).Caption = temp
Next Counter

End Sub

50
 Custom Displays
Using the Custom Document Display feature of ModScan allows you to generate graphical displays of
modbus data representing your specific instrumentation requirements. You can mix and match different
types of data from the same or different slave device and have it displayed in a varity of formats. You can
add simple drawing items such as lines, circles, and rectangles to the display along with customized text and
several built-in graphical items such as bar gauges and historical trend charts.

The Custom Document interface always operates in “Design Mode”. To place an object on the display,
simply hold the left mouse button down and drag a rectangle in the aproximate location you wish to insert
the item. A pop-up dialog will appear allowing you to select from the list of MMI Items which may be
drawn on a ModScan custom display. Each item has associated properties which must be defined to tell
ModScan how the item is to be drawn, (refer to the list of items below). After an item has been added to the
display, its properties may be modified by positioning the mouse over the edge of the item and pressing the
right button. The postion of the item may be changed by using the left mouse button to drag the item to a
new location. If an item is associated with a modbus data point, it will be updated with new data based on
the document’s defined scan rate.

Simple Text Display

Properties associated with a simple text item define, of course, the text string to be displayed as well as the
color and font to be used. Text may be displayed in any color and using any installed font available to
Windows. The selected font also defines the character size. Text may be displayed usiing a
foreground/background color combination or displayed transparently on the existing display background.

Discrete Data Values

Modbus Status Inputs and Coil Status values may be added to a custom display. The properties associated
with a Modbus Discrete Value define the source of the data, (slave address & point address), and configures
the point to be read-only or read-write. Only Coil Status values may be writable from the ModScan and if
so designated, double-clicking on a value displayed to a custom form will initiate a dialog box which allows
the value to be changed. Modbus Discrete Values also contain properties which define the color and font to
be used to display the data.

Register Data Values

Similarly to Discrete Data Values, Register Data Values have associated properties to define the souce of
the data and its read/write status. Unlike the discretes, however, ModScan allows register data to be
displayed in different formats, (such as integer, unsigned, floating-point, etc.). Also, a Register Data Value
may be selected to represent a scaled value according to the conventional modbus range selections of 0-
4095 or 0-9999. This allows ModScan to display register data not only as an absolute value of the contents
of a specified register, but also as a more general purpose process-point representation.

Simple Graphical Items

Custom Documents may also contain several types of graphical items not directly associated with modbus
data. Rectangles, circles, and bitmaps may be added to increase the readability of a display and taylor the
document to personal preferences. Rectangles and Ellipses may be added as either solid or bordered items
using any available color. The respective sizes, (height & width), are specified in pixels and may be
adjusted to suit the taste of the user. These items also contain a property which specifies the drawing order
of the display. Selecting “draw first” allows other MMI items to be drawn on top of a rectangle,
circle, or bitmap.

51
 Bar Chart Items

Bar Chart items allow a modbus register value to be displayed as a colored bar whose amplitute represents
its current value. Bar Charts may be drawn vertically, (bottom to top), or horizontally, (left to right), and
the respective sizes are determined by user defined properties. Properties also define the source of the data
used to update the chart and various drawing options such as the colors to use and whether or not to
surround the bar chart with a border.

Trend Chart Items

A Trend Chart MMI Item allows you to represent one or more modbus register values as a line graph of
amplitude over time. Up to five different variables may be displayed within a Trend Chart item with each
register value represented by a defined pen color and scaled between specified high and low limits.
Properties for the Trend Chart define its update frequency and background color as well as allowing the
chart to be optionally surrounded by a border.

Dials

Dial gauges may also be added to a custom display. Properties for the dial include the bitmap to be used to
draw the face of the dial and the modbus register value representing the source of the data used to update its
value. The dial’s needle may be located anywhere on the bitmap by specifying its X & Y coordinates.
Properties also define the needle width, length, and sweep.

52