PowerBuilder

We begin this article by asking the question: Why would you want to integrate real-time GPS data into your PowerBuilder applications anyway? After all, it's not likely you are going to connect a GPS receiver to your desktop computer and ask yourself where you are currently located. (At least I hope not!)

More likely, you will be utilizing some sort of field service application where you need to know how to get from point A to point B, for example, an insurance assessor who needs to know how to get to the next accident site. For this, the user might use a tablet PC connected to a GPS receiver with some sort of integrated mapping solution. However, as PowerBuilder programmers, how are we to write such applications? Currently, unlike PocketBuilder, there is no built-in support for hardware devices such as GPS receivers. That being said, we will go about the task of "rolling our own" and integrating it with Microsoft MapPoint 2004 to create an application that can plot your location on a map as a function of your current position.

In order to complete this exercise you will need the following:

• A GPS receiver (the Pharos Bluetooth GPS receiver is used in this example)
• Microsoft MapPoint 2004
• PowerBuilder 9.x
• Ian Thain's NMEA parser (look on CodeExchange in the special hardware section)
• Some time to learn!

After reading this article you should be able to:

• Write the serial communications necessary to communicate with your Bluetooth GPS receiver
• Understand the basics of the NMEA protocol and the primary sentence returned by the receiver
• Parse the NMEA messages returned by the GPS receiver
• Convert the latitude and longitude returned by the receiver to decimal degrees (this is necessary for interfacing with MapPoint.)
• Use Microsoft MapPoint 2004 to plot your current latitude and longitude on a map

That being said, we will go step-by-step to create an application that works by reading your current location from the GPS receiver and then sends the latitude and longitude to MapPoint for display on the map. In other words, using this code, you can always see where you are as a function of your current position. Figure 1 provides a picture of the finished product.

Now, how to create it!

Step 1: Make sure you, your computer, and GPS receiver are in an area where you can get decent satellite coverage. Outside is best, but probably not practical, so try near a window. If you are using Bluetooth, you have about 30 feet to play with in regards to the location of your GPS receiver and computer.

Note, for an excellent explanation of how GPS receivers work, see http://electronics.howstuffworks.com/gps.htm.

Step 2: Create a main window and drop a Microsoft MapPoint control on it. Add a button for the purpose of retrieving the GPS data and plotting your position on the map as a function of your current coordinates. Initialize the control with the following code:

ioo_Map = ole_MapControl.Object.NewMap(1)
ole_MapControl.Object.Units = 1

The first statement assigns an instance variable to a new occurrence of the map. In this case, we are specifying the map of North America. We will use the instance variable later as a "pointer" to perform more operations on the control. The second line specifies that we would like our units to be interpreted as kilometers. This is necessary since the GPS receiver will return the current altitude in meters.

Step 3: Declare the global external function prototypes for performing the serial I/O necessary to "talk to" your GPS receiver. You might be wondering why not just use the built-in PowerBuilder I/O functions, for example, FileOpen and FileRead? The underlying reason is that PowerBuilder will buffer the data for you (on top of the native buffering that the OS provides). That can be problematic for serial I/O devices. That is why we are using the kernel calls. Here are their prototypes.

• Function Long CreateFile(ref string lpszName, long fdwAccess, long fdwShareMode, long lpsa, long fdwCreate, long fdwAttrsAndFlags, long hTemplateFile) Library "Kernel32.dll"
• Function Long CloseHandle(Long hObject) Library "Kernel32.dll"
• Function Long ReadFile(Long hFile, ref string lpBuffer, long nBytesToRead, ref Long & nBytesRead, Long lNull) Library "Kernel32.dll"
• Function Long WriteFile(Long hFile, ref string lpBuffer, long nBytesToWrite, ref Long & nBytesWritten, LONG lNull) Library "Kernel32.dll"

Step 4: Add the following functions to your main window. These will be used to get the GPS data out of the receiver. In the next section we will show how to use them together to achieve our means. However first, a little explanation is in order.

• Boolean wf_detect_bt() (see Listing 1)
• Boolean wf_close_bt() (see Listing 2)
• Boolean wf_write_gps() (see Listing 3)
• Boolean wf_read_gps (see Listing 4)
• String wf_get_token(ref string as_string, string as_token) (see Listing 5)

The most interesting of these functions is wf_read_gps(). This does the actual work of reading and parsing the NMEA sentences returned by the receiver. You might be wondering what NMEA is. In a nutshell, it's a protocol for returning real-time position information to a hardware device such as a GPS receiver. An excellent source for information regarding this protocol can be found at www.gpsinformation.org/dale/nmea.htm.

The next order of business is to see how Ian Thain wrote his object to go about parsing a particular NMEA stream. For that, all we have to do is look at the format of an example sentence. Since our code picks off GGA, essential fix data that provide 3D location and accuracy data, we will look at that. Here is a sample:

$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47

Where:
GGA Global Positioning System Fix Data
123519 Fix taken at 12:35:19 UTC
4807.038,N Latitude 48 deg 07.038' N
01131.000,E Longitude 11 deg 31.000' E
1      Fix quality: 0 = invalid
      1 = GPS fix (SPS)
      2 = DGPS fix
      3 = PPS fix
      4 = Real Time Kinematic
      5 = Float RTK
      6 = estimated (dead reckoning) (2.3 feature)
      7 = Manual input mode
      8 = Simulation mode
08      Number of satellites being tracked
0.9      Horizontal dilution of position
45.4,M      Altitude, Meters, above mean sea level
46.9,M      Height of geoid (mean sea level) above WGS84
         ellipsoid
(empty field) time in seconds since last DGPS update
(empty field) DGPS station ID number

What you can see from this example is that the data is comma-delimited. This makes it a prime candidate for easy parsing by storing it in an external DataWindow using the ImportString function. To get at the individual elements, we only need to index them by their position within the DataWindow.