1 Introduction

1.1 Features
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Pricing
1.7 Updates

2 Library Overview

2.1 Dynamic Link Libraries
2.2 Keycode
2.3 Using the Library
2.4 MGC4VB Class
2.5 Dynamic Strings
2.6 Adding MGC4VB to Your Project
2.7 Error Display

3 Compiler Issues

3.1 Visual Basic Makefiles
3.2 Compiling Programs
3.3 VB.NET and Visual Studio
3.4 Visual Basic for Applications (VBA)
3.5 Power Builder

4 Example Programs

4.1 MGCVER
4.2 HELLO
4.3 COMPUTE
4.4 CONVERT
4.5 LATLON
4.6 GPGGA
4.7 GPGLL
4.8 GPGSV
4.9 GPRMC
4.10 GPVTG
4.11 RAW
4.12 GGA_RMC

5 Revision History

1 Introduction

The MarshallSoft GPS Component for Visual Basic (MGC4VB) library is a powerful toolkit that allows software developers to quickly develop GPS applications in VB or VB.NET. The MarshallSoft GPS Component (MGC) is a library of functions providing direct and simple control of GPS data.

A straightforward interface provides the functionality to read and decode standard GPS (Global Positioning System) NMEA 183 sentences from the RS232 serial port as well as compute great circle distances and bearings.

The MarshallSoft GPS Component for Visual Basic library toolkit supports and has been tested with all Win32 versions of Microsoft Visual Basic (VB 4.0,VB 5.0 and VB 6.0) and Microsoft Visual Studio .NET (VB .NET). MGC4VB can also be used with Microsoft VBA (Visual Basic for Applications) such as EXCEL, ACCESS and WORD as well as with Power Builder.

A Win32 DLL (Dynamic Link Library) is provided. MGC4VB runs under all versions of Windows (Windows 95, Windows 98, Windows ME, Windows 2000, Windows 2003, Windows Vista, Windows NT and Windows XP). The MarshallSoft GPS Component DLL (MGC32.DLL) can also be used from any language (C/C++, Visual C++, .NET, Delphi, Visual FoxPro, COBOL, Xbase++, dBase, Cobol, etc.) capable of calling the Windows API. Since the MGC toolkits use the same DLL for all software languages, a developer can, for example, purchase MGC4VB and use the MGC DLL also with MGC4C (C/C++ version).

MGC4VB includes multiple Visual Basic and VB. NET example programs with full source. Several example programs are included that demonstrate using MGC functions to read and decode GPS data. Refer to Section 4 for more details on each of the example programs.

     [PROGRAM]      [DESCRIPTION]
       MGCVER:      Program that displays the MGC4C version & build numbers.
        HELLO:      Program similar to MGCVER but uses the MGC class fMGC.
        GPRMC:      Program that decodes GPRMC sentences.
        GPGGA:      Program that decodes GPGGA sentences.
        GPGLL:      Program that decodes GPGLL sentences.
        GPGSV:      Program that decodes GPGSV sentences.
        GPVTG:      Program that decodes GPVTG sentences.
          RAW:      Program that decodes all sentences.
       LATLON:      Program that graphically displays latitude & longitude.
      COMPUTE:      Computes distances and bearings.
      CONVERT:      Converts between (deg,min,min/1000), (deg,min,sec), etc.
      GGA_RMC:      Program that decoded GPGGA & GPRMC sentences.

Our goal is to provide a robust GPS communications library that you and your customers can depend upon. Contact us if you have any questions.

The evaluation and registered versions are identical except that the evaluation version displays the evaluation (SW_Info) screen. The evaluation version can be used for 60 days.

When comparing the MarshallSoft GPS Component library toolkit against our competition, note that:

1. MGC4VB is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
2. A WIN32 DLL is included.
3. MGC4VB does NOT depend on ActiveX or Microsoft Foundation Class (MFC) libraries or similar "support" libraries.
4. The WIN32 version of MGC is fully thread safe.
5. The MGC4VB functions can be called from applications not capable of using controls.
   
   
   

1.1 Features

Some of the many features of the MarshallSoft GPS Component (MGC) library toolkit are:

• Uses the Windows Win32 API for serial port input. No special Windows driver is required.
• Runs as a background thread unattended. MGC is fully thread safe.
• The most current GPS data is always available on demand.
• Includes support functions such as mgcGreatCircle.
• Can read any GPS NMEA 183 sentence, extracting each field
• Can read and decode GPGGA, GPRMC, GPGLL, and GPGSV navigation sentences.
• Free technical support and updates for one year.
• Royalty free distribution with your compiled application.
• Evaluation versions are fully functional. No unlock code is required.
• Can be used from GUI mode or console mode programs.
• Supports Windows 95/98/Me/NT/2000/2003/XP/Vista).
• MGC4VB is implemented as a standard Windows DLL (will work with all versions of Windows)
• Works with Microsoft Visual Basic (4.0,5.0,6.0) and Microsoft Visual Studio .NET (VB.NET)
• Works with VBA (Visual Basic for Applications) such as Excel as well as Power Builder.
• Does not depend on support libraries. Makes calls to core Windows API functions only.
• Can be used with any application program (in any language) capable of calling Windows API
• Can be purchased with (or without) Ansi C source code.
• Documentation online as well as in printable format.

1.2 Documentation Set

The complete set of documentation consists of three manuals in three formats. This is the first manual (MGC4VB) in the set.

• MGC4VB Programmer's Manual (MGC_4VB.DOC, MGC_4VB.TXT, MGC_4VB.HTM)
• MGC User's Manual (MGC_USR.DOC, MGC_USR.TXT, MGC_USR.HTM)
• MGC Reference Manual (MGC_REF.DOC, MGC_REF.TXT, MGC_REF.HTM)

Each manual comes in three formats:

• Microsoft Word (files ending in .DOC). The best format for printing manuals.
• Hyper Text (files ending in .HTM). Use any web browser to read.
• ASCII Text (files ending in .TXT).

The MGC_4VB Programmer's language specific (Visual Basic) manual and provides information needed to install and compile example programs in a Visual Basic environment. Read this manual first.

The MGC User's Manual (MGC_USR) discusses GPS in general as well as language independent programming issues such as application notes, purchasing and licensing. Read this manual second.

The MGC Reference Manual (MGC_REF) contains details on each individual MGC function.

Use Microsoft Word or Microsoft WordPad to print the document files. The online documentation can be accessed on the MarshallSoft GPS Component for Visual Basic product page at:

    http://www.marshallsoft.com/vb-gps-toolkit.htm

1.3 Example Program

The following example code segment demonstrates the use of some of the MarshallSoft GPS Component library toolkit functions:

     Code = mgcAttach(MGC_KEY_CODE)
     If Code < 0 Then
       MsgBox "ERROR: Cannot attach. Check MGC_KEY_CODE."
       End
     End If
     ' open port
     Code = mgcOpen(ThePort)
     If Code < 0 Then
       MsgBox "ERROR: Cannot open port."
       Exit Sub
     End If
     ' port successfully opened, set sentence type (GPGGS) wanted
     Code = mgcSetInteger(MGC_SET_SENTENCE_TYPE, MGC_SENTENCE_GPGGA)
     While True
       ' lock data buffer
       Code = mgcLockData(1)
       ' get GPGGA sentence
       RefCount = mgcGetData(GPGGA_UTC_TIME, DataBuffer)
       If (RefCount < 0) And (RefCount <> MGC_NO_DATA) Then
         MsgBox "ERROR: " + Str$(RefCount)
         Exit Sub
       End If
       ' 1st time seen this data ?
       If RefCount = 1 Then
         ' get (coded) latitude (assume North in this example)
         iCoded = mgcLatitude()
         ' compute components
         LatDeg = mgcDecodeDeg(iCoded)
         LatMin = mgcDecodeMin(iCoded, LatDeg)
         LatSec = mgcDecodeSec(iCoded, LatDeg, LatMin)
         '
         ' display result as desired ...
         '
       End If
   
       ' unlock data buffer
       Code = mgcLockData(0)
     Wend
   
     Code = mgcClose()
     Code = mgcRelease()
   

In the example program above, the serial port is opened and latitude is continuously read. The latitude components (degrees, minutes, and thousands of a minute) are then computed for display. See the MGC User's Manual (MGC_USR) for details on the various latitude/longitude component descriptions.

This example code segment was taken from the LATLON example program.

Refer to the MGC Reference Manual (MGC_REF) for individual function details.

1.4 Installation

1. Before installation of MGC4VB, your Visual Basic compiler (any 32-bit version) should already be installed on your system and tested.
   
   
2. Unzip MGC4VB20.ZIP (or MGCxxxx.ZIP where xxxx is your Customer ID) using any Windows unzip program.
   
   

2. Run the installation program, SETUP.EXE, which will install all MGC4VB files including copying MGC32.DLL to your Windows directory. No Windows system files are modified.
   
   
3. You are ready to run!

Note that the Windows registry is not modified.

1.5 Uninstalling

Uninstalling MGC4VB is very easy. MGC does not modify the registry.

First, run UINSTALL.BAT, which will delete MGC32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98/Me/XP/2003/Vista or C:\WINNT for Windows NT/2000.

Second, delete the MGC project directory created when installing MGC4VB.

1.6 Pricing

A developer license for the MarshallSoft GPS Component library can be purchased for $115 (or $195 with source code [Ansi C] to the library DLL). Purchasing details can be found in Section 1.4, "How to Purchase", of the MGCC User's Manual (MGC_USR). (http://www.marshallsoft.com/mgc_usr.htm#Section_1.4)

Also see INVOICE.TXT or http://www.marshallsoft.com/order.htm

Registration includes one year of free downloadable updates.

1.7 Updates

After one year, the developer license must be updated to be able to download updates. The developer license can be updated for $30 if ordered within one year of the original purchase (or previous update). From one year to three years, licenses can be updated for $55. After 3 years, licenses can be updated for $75. These updates do not include source code. Source code can be updated for $50 in addition to the cost of the update ($30, $55 or $75).

Note that the registered DLL does not expire.

Also see file UPDATES.TXT.

2 Library Overview

2.1 Dynamic Link Libraries

The MarshallSoft GPS Component Library (CSC) is implemented as a Win32 dynamic link library (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library that is bound to each and every application that uses it at link time.

An important advantage that DLL's have over other "popular" library formats such as VBX or OCX is that DLL's are callable by all Windows applications. Since DLL's are the building blocks of the Windows Operations System, they will not be replaced by a "newer technology".

2.2 Keycode

MGC32.DLL has a keycode encoded within it. Your keycode is a 9 or 10-digit decimal number (unless it is 0), and will be found in the file KEYCODE.BAS and KEYCODE.VB. The keycode for the evaluation version is 0. You will receive a new key code when registering. During SETUP, the keycode is copied to the \APPS sub-directory.

If the error message (value -74) is received when calling mgcAttach, it means that the keycode in your application does not match the keycode in the DLL. After registering, it is best to remove the evaluation version of MGC32.DLL from the Windows search path.

2.3 Using the Library

The MarshallSoft GPS Component Library for Visual Basic has been tested on multiple computers running Windows 95/98/Me/XP/Vista/2003 and Windows NT/2000.

The MGC4VB library has also been tested with all versions of Microsoft Visual Basic and Microsoft Visual Studio .NET. MGC4VB can also be used with Visual Basic for Applications (VBA) such as Microsoft Office, Excel, and Access as well as with Power Builder.

The SETUP installation program will copy the Lib's and DLL to your Windows directory.

2.4 MGC4VB Class

The MGC class "mgcClass" (mgcClass.cls) is a Visual Basic class wrapper for making calls to MGC32.DLL. The class name for each function is the same as the DLL function except the leading "mgc" is replaced by "f".

Those functions that return strings do so by use of the GetDataBuffer property. Instantiate mgcClass as any other class in Visual Basic:

     Dim C As New mgcClass

Also refer to the MarshallSoft GPS Component Reference Manual (MGC_REF), the example project "HELLO" and the file mgcClass.cls.

The use of mgcClass is limited to Visual Basic 5.0 and above since previous versions of Visual Basic do not support classes.

2.5 Dynamic Strings

The Visual Basic language uses a technique known as "garbage collection" to manage string space at runtime and may be called internally at any time by the Visual Basic runtime, asynchronous to what you may be doing in your code.

When passing a string buffer to a DLL function into which text will be copied, it is strongly recommended that the local string be allocated immediately before use. For example, a string buffer is passed to the user defined dllGetMessage function , which copies a text message into it. Note that SPACE$(80) is called immediately before dllGetMessage.

      Dim Code As Integer
      Dim Buffer As String * 80
      ' allocate buffer just before call to dllGetMessage
      Buffer = SPACE$(80)
      ' copy message into 'Buffer'
      Code = dllGetMessage(Buffer, 80)
      ' message text is now in 'Buffer'

This technique is not necessary for passing a string to a DLL function, only when passing a buffer to a DLL into which data is to be placed by the DLL function.

2.6 Adding MGC4VB to Your Project

Copy MGC32.BAS (if running VB_4.0 /5/6), or MGC32.VB (if running VB.Net) into the same directory (folder) as the application program to which you want to add MGC code. You will find these files in the APPS sub-directory (folder) created when you ran SETUP, usually C:\MGC4VB\APPS.

2.6.1 Adding MGC4VB to your VB_4.0 .0, 5.0, or 6.0 Project

Open your existing project with "File", "Open Project". Then choose "Insert", "Module", then add MGC32.BAS and KEYCODE.BAS to your project. If prompted to add "DAO 2.50 Object Library", choose "no".

MGC functions can now be called from your VB program.

2.6.2 Adding MGC4VB to your VB.Net Project

Open your existing project with "File", "Open Project". Then choose "Project", "Add Module", then add MGC32.VB and KEYCODE.VB to your project. MGC functions can now be called from your VB.NET program.

2.7 Error Display

The error message text associated with MGC error codes can be displayed by calling mgcErrorText.

      Function GetErrorText(ByVal ErrorCode As Long) As String
      Dim Code As Long
      Dim Text As String * 128
      Code = mgcErrorText(ErrorCode, Text)
      If Code > 0 Then
        GetErrorText = Text
      Else
        GetErrorText = "Error code " + LTrim$(Str$(ErrorCode))
      End If
      End Function

3. Compiler Issues

The Marshall GPS Component for Visual Basic component library supports and has been tested with all versions of Microsoft Visual Basic (VB3, VB 4, VB 5, VB 6 and VB.NET).

3.1 Visual Basic Makefiles

Project files for 32-bit Visual Basic end with ".VBP". Projects for VB.Net end with ".vbproj".

3.2 Compiling Programs

Choose "File", then "Open Project" from the main Visual Basic menu.

When saving the example programs in VB version 5.0 or VB 6.0 format, answer "no" if asked to add the "Microsoft DAO v2.5 library".

Compile and run MGCVER as the first example. MGCVER should display the version number from MGC32.DLL.

3.3 VB.Net and Visual Studio

There are a few differences between VB 4/5/6 and VB.NET / Visual Studio that affect writing programs that use MGC.

1. Variables that are declared "As Long" in VB4/5/6 are declared "As Integer" in VB.Net.
   
   
2. Fixed length strings are not supported in VB.Net. When calling any MGC function that can return a string (mgcGetString for example), memory for the string variable must be allocated first. For example:

     Dim Buffer As String
     Buffer = Space(80)
     Code = mgcGetString(0, MGC_GET_REGISTRATION, Buffer, 80)
   

3. Some Visual Basic functions must be fully qualified. For example, instead of LEFT, use Microsoft.VisualBasic.Left
   
   
4. The module MGC32.VB (not MGC32.BAS) must be included in all VB.Net programs.

3.4 Visual Basic for Applications (VBA)

The MarshallSoft GPS library can be used with Microsoft VBA applications such as EXCEL, ACCESS, and Microsoft Office.

Start EXCEL (or other 32-bit Office VBA program such as WORD or ACCESS), then enter design mode. Enable the "Controls Toolbox", choose "Tools" on the menu bar, then "Customize", and then check "Control Toolbox". From the control toolbox, choose and position a "Command Button". This will create code that looks like

     Private Sub CommandButton1_Click()
   
     End Sub
   
Replace the generated code with MODULE32.BAS.  The easiest way to do this is to paste from the clipboard.

Exit design mode and then press the command button to start the VBA example program.

3.5 Power Builder

MGC can also be used with 32 bit Power Builder applications.  See PBUILDER.TXT in the \APPS subdirectory for more information.
   
     CSC32.PBI : Power Builder declaration file.
   

4 Example Programs

Several example programs are included in MGC4VB. There is also an example program (HELLO), which uses the VB class "mgcClass", but requires VB 5 or VB 6 (which support classes).

Example programs are located in the \APPS sub-directory created by SETUP.

4.1 MGCVER

The first example program is the program MGCVER (MGC Version) that displays the MGC library version number and registration string. Its purpose is display the MGC version, build, and registration string as well as to verify that MGC32.DLL is being found and loaded by Windows.

The project files are:

     MGCVER.VBP    : for (32-bit) VB 4.0 and above.
     MGCVER.VBPROJ : for VB.Net.

4.2 HELLO

The HELLO example program is similar to MGCVER except that it uses the MGC class mgcClass.cls. See mgcClass.cls. Visual Basic 5 or above is required for programs using VB classes.

4.3 COMPUTE

COMPUTE is a Visual Basic program that computes great circle distances and bearings from a pair of latitude/longitude values.

The project files are:

     COMPUTE.VBP    : for (32-bit) VB 4.0 and above.
     COMPUTE.VBPROJ : for VB.Net.
   

4.4 CONVERT

CONVERT is a Visual Basic program that converts latitude (or longitude) between (deg, min, min/1000), (deg, min, sec), and single integer encoding.

The project files are:
   
     CONVERT.VBP    : for (32-bit) VB 4.0 and above.
   

4.5 LATLON

LATLON is a VB example program that continuously displays latitude and longitude .

The project files are:

     LATLON.VBP    : for (32-bit) VB 4.0 and above.
     LATLON.VBPROJ : for VB.Net.
   

4.6 GPGGA

GPGGA is a VB program that displays all NMEA GPGGA sentences.

The project files are:

     GPGGA.VBP    : for (32-bit) VB 4.0 and above.
     GPGGA.VBPROJ : for VB.Net.
   

4.7 GPGLL

GPGLL is a VB program that displays all NMEA GPGLL sentences.

The project files are:
   
     GPGGL.VBP    : for (32-bit) VB 4.0 and above.
   

4.8 GPGSV

GPGSV is a VB program that displays all NMEA GPGSV sentences.

The project files are:
   
     GPGSV.VBP    : for (32-bit) VB 4.0 and above.
   

4.9 GPRMC

GPRMC is a VB program that displays all NMEA GPRMC sentences.

The project files are:
   
     GPRMC.VBP    : for (32-bit) VB 4.0 and above.
   

4.10 GPVTG

GPVTG is a VB program that displays all NMEA GPVTG sentences.

The project files are:
   
     GPVTG.VBP    : for (32-bit) VB 4.0 and above.
   

4.11 RAW

RAW is a VB program that displays all NMEA sentences.

The project files are:

     RAW.VBP    : for (32-bit) VB 4.0 and above.
     RAW.VBPROJ : for VB.Net.
   

5 Revision History

The MarshallSoft GPS Component DLL (MGC32.DLL) is written in ANSI C. All language versions of MGC (C/C++, Delphi, Visual Basic, PowerBASIC, etc) use the same identical DLL.

Version 1.2: February 7, 2003.

• The initial release of the Visual Basic version MGC4VB.

Version 1.3: August 9, 2004

• Increased maximum number of fields from 19 to 20.
• Receive buffer size increased from 256 to 1024.
• Overflow wraps to empty.
• Added MGC_SET_SLEEP to mgcSetInteger (sets work buffer sleep time).
• Added mgcStatus() function to return GPS data status.

Version 1.4 March 3, 2005

• Added $GPVTG sentence type.
• Interval diagnostics added.

Version 2.0: July 26, 2007

The "Coded Integer" angles returned by MGC functions are now returned in units of hundred-thousandths of a degree rather than thousandths of a minute.

• mgcBearing returns the bearing in units of hundred-thousandths of a degree (100000 units = 1 deg).
• Two sentence types can be specified rather than just one. See GGA_RMC.C
• mgcGetSentenceType added that returns the current sentence type (defined in mgc.bas)
• mgcNewLatitude added that returns a new latitude at a specified distance.
• mgcNewLongitude added that returns a new longitude at a specified distance.