GetSatellitesInView

Description

Populates a GPSSatellitesInView structure with data about the satellites currently in view.

Applies to

GPS and SerialGPS objects

Syntax

Integer GPSname.GetSatellitesInView( GPSSatellitesInView )

Argument	Description
GPSname	Name of the GPS or SerialGPS object
GPSSatellitesInView	Structure passed by reference that stores position information for the satellites in view

Returns

Integer. Returns 1 for success and 100 or a negative number for an error. The following is a list of possible error codes and their meanings:

100 End of buffer. The requested data was not found.
-1 General error.
-10 Invalid object. Could occur if the GPS object instance is corrupted.
-13 Not previously opened. This function cannot be called until a GPS object or SerialGPS object has been successfully opened.
-14 Read timeout. Occurs when the timeout interval (a ConfigParams property of the SerialGPS object) is exceeded.
-15 Read Failure. Unable to read the file or serial port.
-16 Parser Error. Parser is unable to interpret a sentence. This error is generated when nonstandard tokens are discovered while parsing the GPS data.
-17 Checksum Error. Most GPS sentences end in a two-digit checksum value. The PocketBuilder parser verifies this value and reports a checksum error if the calculated value does not match the stated value.

Usage

Use this function to populate a GPSSatellitesInView structure with information about the position of each satellite currently in view and the accuracy of the position fix. The HDOP (Horizontal Dilution of Precision) and VDOP (Vertical Dilution of Precision) properties indicate the level of confidence in the accuracy of measurements related to the horizontal and vertical positions of the satellites, based on current satellite geometry. A lower value indicates greater confidence.

Position information is returned in an array of GPSSatellitePosition structures, each of which contains information about the azimuth, elevation, signal strength, and PRN number of each of the satellites currently in view. Up to 12 satellites can be listed in the satellite array. Use the UpperBound function to determine the number of satellites listed.

Examples

Example 1

The following lines create a SerialGPS object, retrieve information about the satellites used for the current position fix, test the validity of the GPSSatellitesInView object, and write data to a multiline edit box:

// instance variable: GPSSatellitePosition iGPS_SP[]

SerialGPS myGPS

GPSSatellitesInView mySIV

Integer rc

myGPS = CREATE SerialGPS
myGPS.open()
...
rc = myGPS.getSatellitesInView(mySIV)

if rc = 1 then

mle_1.text = "HDOP: " + String(mySiv.HDOP) + "~r~n"
mle_1.text += "VDOP: " + String(mySiv.VDOP) + "~r~n"
mle_1.text += "Satellites in view: PRN, Azimuth, " &
   + "Elevation, SNR values. ~r~n"

iGPS_SP = mySIV.Satellite[]
integer count
for count = 1 to UpperBound(iGPS_SP)
   mle_1.text += String(iGPS_SP[i].PRN + ", "
   mle_1.text += String(iGPS_SP[i].Azimuth + ", "
   mle_1.text += String(iGPS_SP[i].Elevation + ", "
   mle_1.text += String(iGPS_SP[i].SNR + "~r~n "
end for

else

//process error message

end if