ProSoft MVI ADMNET Series Instruction Manual

MVI-ADMNET
'C' Programmable
Ethernet Module
Developer's Guide
December 13, 2006

Please Read This Notice
Successful application of this module requires a reasonable working knowledge of the Allen-
Bradley hardware, the MVI-ADMNET Module and the application in which the combination is to be
used. For this reason, it is important that those responsible for implementation satisfy themselves
that the combination will meet the needs of the application without exposing personnel or
equipment to unsafe or inappropriate working conditions.
This manual is provided to assist the user. Every attempt has been made to assure that the
information provided is accurate and a true reflection of the product's installation requirements. In
order to assure a complete understanding of the operation of the product, the user should read all
applicable Allen-Bradley documentation on the operation of the Allen-Bradley hardware.
Under no conditions will ProSoft Technology, Inc. be responsible or liable for indirect or
consequential damages resulting from the use or application of the product.
Reproduction of the contents of this manual, in whole or in part, without written permission from
ProSoft Technology, Inc. is prohibited.
Information in this manual is subject to change without notice and does not represent a
commitment on the part of ProSoft Technology, Inc. Improvements and/or changes in this manual
or the product may be made at any time. These changes will be made periodically to correct
technical inaccuracies or typographical errors.
Your Feedback Please
We always want you to feel that you made the right decision to use our products. If you have
suggestions, comments, compliments or complaints about the product, documentation or support,
please write or call us.
ProSoft Technology, Inc.
1675 Chester Avenue, Fourth Floor
Bakersfield, CA 93301
[phone]
[phone] (Fax)
http://www.prosoft-technology.com
Copyright © ProSoft Technology, Inc. 2000 - 2006. All Rights Reserved.
MVI-ADMNET Developer's Guide
December 13, 2006

Contents MVI-ADMNET ♦'C' Programmable
Ethernet Module
ProSoft Technology, Inc. Page 3 of 90
December 13, 2006
Contents
PLEASE READ THIS NOTICE...........................................................................................................2
Your Feedback Please ..................................................................................................................2
1INTRODUCTION .........................................................................................................................5
1.1 Definitions......................................................................................................................5
1.2 Operating System..........................................................................................................6
2PREPARING THE MVI-ADMNET MODULE...............................................................................7
2.1 Package Contents .........................................................................................................7
2.2 Jumper Locations and Settings...................................................................................7
2.2.1 Setup Jumper.................................................................................................................7
2.2.2 Port 1 and Port 2 Jumpers .............................................................................................7
2.3 Connections...................................................................................................................8
2.3.1 MVI-ADMNET Communication Ports.............................................................................8
3SETTING UP YOUR DEVELOPMENT ENVIRONMENT............................................................9
3.1 Setting Up Your Compiler.............................................................................................9
3.1.1 Configuring Digital Mars C++ 8.49.................................................................................9
3.1.2 Configuring Borland C++5.02 ......................................................................................19
3.2 Setting Up WINIMAGE.................................................................................................26
3.3 Installing and Configuring the Module......................................................................26
3.3.1 Using Side-Connect (Requires Side-Connect Adapter) (MVI71).................................27
4UNDERSTANDING THE MVI-ADMNET API............................................................................31
4.1 API Libraries.................................................................................................................31
4.1.1 Calling Convention.......................................................................................................31
4.1.2 Header File...................................................................................................................32
4.1.3 Sample Code ...............................................................................................................32
4.1.4 Multithreading Considerations .....................................................................................32
4.2 Development Tools .....................................................................................................32
4.3 Theory of Operation ....................................................................................................32
4.3.1 ADM API ......................................................................................................................32
4.3.2 ADMNET API Architecture...........................................................................................32
4.4 ADM API Files ..............................................................................................................33
4.4.1 ADM Interface Structure ..............................................................................................33
5APPLICATION DEVELOPMENT FUNCTION LIBRARY: ADMNET API ................................37
5.1 ADMNET API Functions..............................................................................................37
ADMNET API Initialize Functions...............................................................................................39
ADM_init_socket ........................................................................................................................39
ADM_open_sk ...........................................................................................................................40
ADMNET API Release Socket Functions ..................................................................................41
ADM_release_sockets ...............................................................................................................41
ADM_close_sk ...........................................................................................................................42
ADMNET API Send Socket Functions.......................................................................................43
ADM_send_socket.....................................................................................................................43
ADM_send_sk............................................................................................................................44
ADMNET API Receive Socket Functions ..................................................................................45
ADM_receive_socket .................................................................................................................45
ADM_receive_sk........................................................................................................................46

MVI-ADMNET ♦'C' Programmable Contents
Ethernet Module
Page 4 of 90 ProSoft Technology, Inc.
December 13, 2006
ADMNET API Miscellaneous Functions.................................................................................... 47
ADM_NET_GetVersionInfo ....................................................................................................... 47
ADM_is_sk_open ...................................................................................................................... 48
6WATTCP API FUNCTIONS...................................................................................................... 49
6.1 WATTCP API Functions ............................................................................................. 49
ADMNET API Initialize Functions..............................................................................................51
sock_init..................................................................................................................................... 51
ADMNET API System Functionality .......................................................................................... 52
tcp_tick 52
tcp_open.................................................................................................................................... 53
tcp_open_fast............................................................................................................................ 54
udp_open................................................................................................................................... 55
udp_open_fast........................................................................................................................... 56
resolve 57
sock_mode ................................................................................................................................ 58
sock_established....................................................................................................................... 59
ip_timer_init ............................................................................................................................... 60
ip_timer_expired........................................................................................................................ 61
set_timeout ................................................................................................................................ 62
chk_timeout ............................................................................................................................... 63
sockerr 64
sockstate ................................................................................................................................... 65
gethostid .................................................................................................................................... 66
ADMNET API Release Socket Functions.................................................................................. 67
sock_exit.................................................................................................................................... 67
sock_abort ................................................................................................................................. 68
sock_close................................................................................................................................. 69
ADMNET API Send Socket Functions....................................................................................... 70
sock_write.................................................................................................................................. 70
sock_fastwrite............................................................................................................................ 71
sock_flush.................................................................................................................................. 72
sock_flushnext........................................................................................................................... 73
sock_puts .................................................................................................................................. 74
sock_putc .................................................................................................................................. 75
ADMNET API Receive Socket Functions.................................................................................. 76
sock_read .................................................................................................................................. 76
sock_fastread ............................................................................................................................ 77
tcp_listen ................................................................................................................................... 78
sock_gets .................................................................................................................................. 79
sock_getc .................................................................................................................................. 80
sock_dataready ......................................................................................................................... 81
rip 82
inet_ntoa.................................................................................................................................... 83
inet_addr.................................................................................................................................... 84
SUPPORT, SERVICE & WARRANTY............................................................................................. 85
Module Service and Repair........................................................................................................85
General Warranty Policy – Terms and Conditions.................................................................. 86
Limitation of Liability..................................................................................................................87
RMA Procedures.........................................................................................................................87
INDEX...............................................................................................................................................89

Introduction MVI-ADMNET ♦'C' Programmable
Ethernet Module
ProSoft Technology, Inc. Page 5 of 90
December 13, 2006
1 Introduction
In This Chapter
¾Definitions ................................................................................ 5
¾Operating System .................................................................... 6
This document provides information needed to develop application programs for
the MVI ADM Ethernet Serial Communication Module. The MVI suite of modules
is designed to allow devices with a serial and Ethernet port to be accessed by a
PLC. The modules and their corresponding platforms are as follows:
MVI46 - 1746 (SLC)
MVI56 - 1756 (ControlLogix)
MVI69 - 1769 (CompactLogix)
MVI71 - 1771 (PLC)
The modules are programmable to accommodate devices with unique Serial-
Ethernet protocols.
This document includes information about the available ethernet communication
software API libraries, programming information, and example code. For tools,
module configuration, serial communication software API, serial communication
programming information, and example code for both the module and the PLC,
refer to MVI ADM Developer's Guide.
This document assumes the reader is familiar with software development in the
16-bit DOS environment using the C programming language. This document also
assumes that the reader is familiar with Allen-Bradley programmable controllers
and the PLC platform.
1.1 Definitions
Term Definition
API Application Programming Interface
Backplane Refers to the electrical interface, or bus, to which modules connect when
inserted into the rack. The MVI-ADMNET module communicates with the
control processor(s) through the PLC backplane.
BIOS Basic Input Output System. The BIOS firmware initializes the module at
power up, performs self-diagnostics, and provides a DOS-compatible
interface to the console and Flashes the ROM disk.
Controller The PLC or other controlling processor that communicates with the MVI
module directly over the backplane or via a network or remote I/O adapter.
Input Image Refers to a contiguous block of data that is written by the module application
and read by the controller. The input image is read by the controller once
each scan. Also referred to as the input file.

MVI-ADMNET ♦'C' Programmable Introduction
Ethernet Module
Page 6 of 90 ProSoft Technology, Inc.
December 13, 2006
Term Definition
Library Refers to the library file containing the API functions. The library must be
linked with the developer's application code to create the final executable
program.
Long 32-bit value.
Word 16-bit value
Byte 8-bit value
MVI Suite The MVI suite consists of line products for the following Allen-Bradley
platforms:
PLC
ControlLogix
CompactLogix
SLC
1.2 Operating System
The MVI module includes General Software Embedded DOS 6-XL. This
operating system provides DOS compatibility along with real-time multitasking
functionality. The operating system is stored in Flash ROM and is loaded by the
BIOS when the module boots.
DOS compatibility allows user applications to be developed using standard DOS
tools, such as Digital Mars and Borland compilers. User programs may be
executed automatically by loading them from either the CONFIG.SYS file or an
AUTOEXEC.BAT file. In addition to MVI-ADMNET, ADMTCP.CFG is required to
assign an IP address to the module. Users can store the ADMTCP.CFG file
directly to a Compact Flash.
The format of the ADMTCP.CFG is as follows:
# ProLinx Communication Gateways, Inc.
# Default private class 3 address
my_ip=192.168.0.148
# Default class 3 network mask
netmask=255.255.255.0
# name server 1 up to 9 may be included
# nameserver=xxx.xxx.xxx.xxx
# name server 2
# nameserver=xxx.xxx.xxx.xxx
# The gateway I wish to use
gateway=192.168.0.1
# some networks (class 2) require all three parameters
# gateway,network,subnetmask
# gateway 192.168.0.1,192.168.0.0,255.255.255.0
# The name of my network
# domainslist="mynetwork.name"
Note: DOS programs that try to access the video or keyboard hardware
directly will not function correctly on the MVI module. Only programs that use
the standard DOS and BIOS functions to perform console I/O are compatible.

Preparing the MVI-ADMNET Module MVI-ADMNET ♦'C' Programmable
Ethernet Module
ProSoft Technology, Inc. Page 7 of 90
December 13, 2006
2 Preparing the MVI-ADMNET Module
In This Chapter
¾Package Contents.................................................................... 7
¾Jumper Locations and Settings................................................ 7
¾Connections ............................................................................. 8
2.1 Package Contents
Your MVI-ADMNET package includes:
MVI-ADMNET Module
ProSoft Technology Solutions CD-ROM (includes all documentation, sample
code, and sample ladder logic).
Null Modem Cable
Mini-DIN to DB-9 Cable
2.2 Jumper Locations and Settings
Each module has three jumpers:
Setup
Port 1
Port 2
2.2.1 Setup Jumper
The Setup jumper, located at the bottom of the module, should have the two pins
jumpered when programming the module. Once programmed, the jumper should
be removed.
2.2.2 Port 1 and Port 2 Jumpers
These jumpers, located at the bottom of the module, configure the port settings
to RS-232, RS-422, or RS-485. By default, the jumpers for both ports are set to
RS-232. These jumpers must be set properly before using the module.

MVI-ADMNET ♦'C' Programmable Preparing the MVI-ADMNET Module
Ethernet Module
Page 8 of 90 ProSoft Technology, Inc.
December 13, 2006
2.3 Connections
2.3.1 MVI-ADMNET Communication Ports
The MVI-ADMNET module has three physical connectors; two application ports
and one debugging port, with an RJ45 plug and Ethernet port located on the front
of the module.

Setting Up Your Development Environment MVI-ADMNET ♦'C' Programmable
Ethernet Module
ProSoft Technology, Inc. Page 9 of 90
December 13, 2006
3 Setting Up Your Development Environment
In This Chapter
¾Setting Up Your Compiler ........................................................ 9
¾Setting Up WINIMAGE........................................................... 26
¾Installing and Configuring the Module .................................... 26
3.1 Setting Up Your Compiler
There are some important compiler settings that must be set in order to
successfully compile an application for the MVI platforms. The following topics
describe the setup procedures for each of the supported compilers.
3.1.1 Configuring Digital Mars C++ 8.49
The following procedure allows you to successfully build the sample ADM code
supplied by Prosoft Technology using Digital Mars C++ 8.49. After verifying that
the sample code can be successfully compiled and built, you can modify the
sample code to work with your application.
Note: This procedure assumes that you have successfully installed Digital
Mars C++ 8.49 on your workstation.
Downloading the Sample Program
The sample code files are located in the ADM_TOOL_MVI.ZIP file. This zip file is
available from the CD-ROM shipped with your system or from the ProSoft-
Technology.com web site. When you unzip the file, you will find the sample code
files in \ADM_TOOL_MVI\SAMPLES\.

MVI-ADMNET ♦'C' Programmable Setting Up Your Development Environment
Ethernet Module
Page 10 of 90 ProSoft Technology, Inc.
December 13, 2006
Building an Existing Digital Mars C++ 8.49 ADM Project
1 Start Digital Mars C++ 8.49, and then click Project →Open from the Main
Menu.
2 From the Folders field, navigate to the folder that contains the project
(C:\ADM_TOOL_MVI\SAMPLES\…).
3 In the File Name field, click on the project name (56adm-si.prj).
4 Click OK. The Project window appears:
5 Click Project →Rebuild All from the Main Menu to create the .exe file. The
status of the build will appear in the Output window:
Porting Notes: The Digital Mars compiler classifies duplicate library names as
Level 1 Errors rather than warnings. These errors will manifest themselves as
"Previous Definition Different : function name". Level 1 errors are non-fatal and
the executable will build and run. The architecture of the ADM libraries will
cause two or more of these errors to appear when the executable is built. This
is a normal occurrence. If you are building existing code written for a different
compiler you may have to replace calls to run-time functions with the Digital

Setting Up Your Development Environment MVI-ADMNET ♦'C' Programmable
Ethernet Module
ProSoft Technology, Inc. Page 11 of 90
December 13, 2006
Mars equivalent. Refer to the Digital Mars documentation on the Run-time
Library for the functions available.
6 The executable file will be located in the directory listed in the Compiler
Output Directory field. If it is blank then the executable file will be located in
the same folder as the project file. The Project Settings window can be
accessed by clicking Project →Settings from the Main Menu.
Creating a New Digital Mars C++ 8.49 ADM Project
1 Start Digital Mars C++ 8.49, and then click Project →New from the Main
Menu.
2 Select the path and type in the Project Name.

MVI-ADMNET ♦'C' Programmable Setting Up Your Development Environment
Ethernet Module
Page 12 of 90 ProSoft Technology, Inc.
December 13, 2006
3 Click Next.
4 In the Platform field, choose DOS.
5 In the Project Settings choose Release if you do not want debug information
included in your build.
6 Click Next.
7 Select the first source file necessary for the project.
8 Click Add.
9 Repeat this step for all source files needed for the project.
10 Repeat the same procedure for all library files (.lib) needed for the project.

Setting Up Your Development Environment MVI-ADMNET ♦'C' Programmable
Ethernet Module
ProSoft Technology, Inc. Page 13 of 90
December 13, 2006
11 Choose Libraries (*.lib) from the List Files of Type field to view all library files:
12 Click Next.
13 Add any defines or include directories desired.
14 Click Finish.

MVI-ADMNET ♦'C' Programmable Setting Up Your Development Environment
Ethernet Module
Page 14 of 90 ProSoft Technology, Inc.
December 13, 2006
15 The Project window should now contain all the necessary source and library
files as shown in the following window:
16 Click Project →Settings from the Main Menu.
17 These settings were set when the project was created. No changes are
required. The executable must be built as a DOS executable in order to run
on the MVI platform.

Setting Up Your Development Environment MVI-ADMNET ♦'C' Programmable
Ethernet Module
ProSoft Technology, Inc. Page 15 of 90
December 13, 2006
18 Click the Directories tab and fill in directory information as required by your
project's directory structure.
19 If the fields are left blank then it is assumed that all of the files are in the
same directory as the project file. The output files will be placed in this
directory as well.
20 Click on the Build tab, and choose the Compiler selection. Confirm that the
settings match those shown in the following screen:

MVI-ADMNET ♦'C' Programmable Setting Up Your Development Environment
Ethernet Module
Page 16 of 90 ProSoft Technology, Inc.
December 13, 2006
21 Click Code Generation from the Topics field and ensure that the options
match those shown in the following screen:
22 Click Memory Models from the Topics field and ensure that the options
match those shown in the following screen:

Setting Up Your Development Environment MVI-ADMNET ♦'C' Programmable
Ethernet Module
ProSoft Technology, Inc. Page 17 of 90
December 13, 2006
23 Click Linker from the Topics field and ensure that the options match those
shown in the following screen:
24 Click Packing & Map File from the Topics field and ensure that the options
match those shown in the following screen:

MVI-ADMNET ♦'C' Programmable Setting Up Your Development Environment
Ethernet Module
Page 18 of 90 ProSoft Technology, Inc.
December 13, 2006
25 Click Make from the Topics field and ensure that the options match those
shown in the following screen:
26 Click OK.
27 Click Parse →Update All from the Project Window Menu. The new settings
may not take effect unless the project is updated and reparsed.
28 Click Project →Build All from the Main Menu.
29 When complete, the build results will appear in the Output window:
The executable file will be located in the directory listed in the Compiler Output
Directory box of the Directories tab (that is, C:\ADM_TOOL_MVI\SAMPLES\…).
The Project Settings window can be accessed by clicking Project →Settings
from the Main Menu.
Porting Notes: The Digital Mars compiler classifies duplicate library names as
Level 1 Errors rather than warnings. These errors will manifest themselves as
"Previous Definition Different : function name". Level 1 errors are non-fatal and
the executable will build and run. The architecture of the ADM libraries will
cause two or more of these errors to appear when the executable is built. This
is a normal occurrence. If you are building existing code written for a different
compiler you may have to replace calls to run-time functions with the Digital
Mars equivalent. Refer to the Digital Mars documentation on the Run-time
Library for the functions available.

Setting Up Your Development Environment MVI-ADMNET ♦'C' Programmable
Ethernet Module
ProSoft Technology, Inc. Page 19 of 90
December 13, 2006
3.1.2 Configuring Borland C++5.02
The following procedure allows you to successfully build the sample ADM code
supplied by Prosoft Technology. using Borland C++ 5.02. After verifying that the
sample code can be successfully compiled and built, you can modify the sample
code to work with your application.
Note: This procedure assumes that you have successfully installed Borland
C++ 5.02 on your workstation.
Downloading the Sample Program
The sample code files are located in the ADM_TOOL_MVI.ZIP file. This zip file is
available from the CD-ROM shipped with your system or from the ProSoft-
Technology.com web site. When you unzip the file, you will find the sample code
files in \ADM_TOOL_MVI\SAMPLES\.
Building an Existing Borland C++ 5.02 ADM Project
1 Start Borland C++ 5.02, and then click Project →Open Project from the
Main Menu.
2 From the Directories field, navigate to the directory that contains the project
(C:\adm\sample).
3 In the File Name field, click on the project name (adm.ide).

MVI-ADMNET ♦'C' Programmable Setting Up Your Development Environment
Ethernet Module
Page 20 of 90 ProSoft Technology, Inc.
December 13, 2006
4 Click OK. The Project window appears:
5 Click Project →Build All from the Main Menu to create the .exe file. The
Building ADM window appears when complete:
6 When Success appears in the Status field, click OK.