GEOLOCATION
See alsoManage geographical data, including zones, user positions and tracking.
Modes dealing with user positions are only effective for users connected with the SnapVue mobile application, and if tracking extensions are installed.
| Mode | Mnemonic | Syntax |
| 1 | GETUSERPOSITION | 1 |
| 2 | GETLATITUDE | 2 |
| 3 | GETLONGITUDE | |
| 4 | GETALTITUDE | |
| 5 | FORMATPOSITION | 3 |
| 6 | ISVALIDPOSITION | 4 |
| 7 | GETDISTANCE | 5 |
| 8 | GETUSERZONE | 1 |
| 9 | GETUSERPOSACCURACY | 6 |
| 10 | GETUSERSATPOSITION | 7 |
| 11 | GETUSERSINZONE | 8 |
| 13 | GETUSERSCOUNT | 9 |
| 14 | ISUSERINZONE | 10 |
| 15 | ISUSERATPOSITION | 11 |
| 16 | GETSPECIFICUSER | 12 |
| 17 | GETUSERSCOUNTFROMSTR | 13 |
| 18 | GETCLOSESTUSERBYPOS | 14 |
| 19 | GETZONEPOSITION | 15 |
Properties common to more than one mode
|
Argument |
Meaning |
| UserName | The name of a user as configured in User Accounts. Type STR. |
| Position | A string in the format "lat:Value lon:Value alt:Value" where Value are numbers of any numeric type and expressed in degrees. Example "lat:1.23 lon:4.56 alt:7.89" |
| Longitude | A longitude value in degrees. Any numeric type. |
| Latitude | A latitude value in degrees. Any numeric type. |
| Altitude | An altitude value in meters. Any numeric type. |
| ProfileRole | The role of a user, as defined by the Role property of the profile attached to the user account. Type STR. |
| ProfileLevelMin | The lowest profile level. Profile levels are only available when the advanced security strategy is enabled. Any numeric type. |
| ProfileLevelMax | The highest profile level. Profile levels are only available when the advanced security strategy is enabled. Any numeric type. |
| ZoneId | The name of a zone as configured in the Geographical Data node of the Application Explorer. Type STR. |
| ListOfUsers |
List of users as returned by GETUSERSATPOSITION or GETUSERSINZONE. Type STR. |
| Radius |
A radius in meters. Any numeric type. |
Syntax 1
StrVal = GEOLOCATION (Mode, UserName);
Return type: STR.
Execution
|
Mode |
Mnemonic |
Action |
| 1 | GETUSERPOSITION |
Retrieves the position (latitude, longitude, altitude) of the user UserName. |
| 8 | GETUSERZONE |
Retrieves the name of the zone in which the user UserName is currently located. Returns: The name of the zone. An empty string is returned if the user does not exist or his/her position is not available. |
Syntax 2
DblVal = GEOLOCATION (Mode, Position);
Return type: DOUBLE.
Execution
|
Mode |
Mnemonic |
Action |
| 2 | GETLATITUDE |
Get the latitude of the position Position. Return: The latitude value in degrees if OK, else 0 (invalid or missing latitude). |
| 3 | GETLONGITUDE |
Returns the longitude of the position Position. Return: The longitude value in degrees if OK, else 0 (invalid or missing longitude). |
| 4 | GETALTITUDE |
Returns the altitude of the position Position. Return: The altitude value in meters if OK, else 0 (invalid or missing altitude). |
It is recommended to test the validity of the Position argument with the mode ISVALIDPOSITION prior to using these modes to extract position components. By doing so, the script designer is able to ensure that the return value 0 is the actual value extracted (latitude or altitude 0 for example), or if the position passed as argument is incorrect.
Syntax 3
StrVal = GEOLOCATION (Mode, Latitude, Longitude, Altitude);
Return type: STR.
Execution
|
Mode |
Mnemonic |
Action |
| 7 | FORMATPOSITION |
Format the value of a position string using the supplied longitude, latitude and altitude. Return: A string in the Position format if OK, else 0 (invalid arguments). |
Syntax 4
IntVal = GEOLOCATION (Mode, Position);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 6 | ISVALIDPOSITION |
Check if the format of the supplied Position string is a valid position. Return: 1 if the position is valid, 0 if it is not, else -1 (invalid arguments). |
Syntax 5
DblVal = GEOLOCATION (Mode, PositionA, PositionB);
Return type: DOUBLE.
|
Argument |
Meaning |
|
PositionA PositionB |
Geographic positions in the Position format. |
Execution
|
Mode |
Mnemonic |
Action |
| 8 | GETDISTANCE |
Calculate the distance between two points. Return: The distance in meters if OK, else -1. |
Syntax 6
DblVal = GEOLOCATION (Mode, UserName);
Return type: DOUBLE.
Execution
|
Mode |
Mnemonic |
Action |
| 9 | GETUSERPOSACCURACY |
Calculate the radius of accuracy of the specified user’s position. Return: The radius in meters if OK, else -1. |
Syntax 7
StrVal = GEOLOCATION (Mode, Latitude, Longitude, Radius[, ProfileRole [, ProfileLevelMin [, ProfileLevelMax]]]);
Return type: STR.
Execution
|
Mode |
Mnemonic |
Action |
| 10 | GETUSERSATPOSITION |
Retrieve the list of users present nearby the position specified by Latitude, Longitude and Radius. The list of users can optionally be filtered by profile role and profile level. Return: A string containing a comma separated list of users. An empty string is returned if arguments are invalid or if no user is detected nearby the position. |
Syntax 8
StrVal = GEOLOCATION (Mode, ZoneId[, ProfileRole [, ProfileLevelMin [, ProfileLevelMax]]]);
Return type: STR.
Execution
|
Mode |
Mnemonic |
Action |
| 11 | GETUSERSINZONE |
Retrieve the list of users present in the zone ZoneId. The list of users can optionally be filtered by profile role and profile level. Return: A string containing a comma separated list of users. An empty string is returned if arguments are invalid or if no user is detected nearby the position. |
Syntax 9
IntVal = GEOLOCATION (Mode[, ProfileRole [, ProfileLevelMin [, ProfileLevelMax]]]);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 13 | GETUSERSCOUNT |
Retrieve the total number of users in the entire project, optionally filtered by profile role and browse level. Return: The number of users if OK, else -1. |
Syntax 10
IntVal = GEOLOCATION (Mode, UserName, ZoneId);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 14 | ISUSERINZONE |
Check if the user is located at the zone ZoneId. Return: 1 if the user is located in the zone, else 0 if not, else -1 (invalid arguments, unknown user, no position information for the user). |
Syntax 11
IntVal = GEOLOCATION (Mode, UserName, Latitude, Longitude, Radius);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 15 | ISUSERATPOSITION |
Check if the user is located at the position specified by Latitude, Longitude and Radius. Return: 1 if the user is located at the position, 0 if not, else -1 (invalid arguments, unknown user, no position information for the user). |
Syntax 12
StrVal = GEOLOCATION (Mode, ListOfUsers, Index);
Return type: STR.
|
Argument |
Meaning |
| Index | A position within the list of users. Any numeric type. |
Execution
|
Mode |
Mnemonic |
Action |
| 16 | GETSPECIFICUSER |
Retrieve the name of the user at position Index in the list of users ListOfUsers. Return: A string containing the name of the user if OK, else an empty string (invalid arguments). |
Syntax 13
IntVal = GEOLOCATION (Mode, ListOfUsers);
Return type: INTEGER.
Execution
|
Mode |
Mnemonic |
Action |
| 17 | GETUSERSCOUNTFROMSTR |
Retrieve the number of users in the ListOfUsers. Return: The number of users, else an empty string (invalid arguments). |
Syntax 14
StrVal = GEOLOCATION (Mode, Latitude, Longitude[, ProfileRole [, ProfileLevelMin [, ProfileLevelMax [, Index]]]]);
Return type: STR.
|
Argument |
Meaning |
| Index | The index of the user in the list. 1 = the first closest, 2 = the second closest, etc. |
Execution
|
Mode |
Mnemonic |
Action |
| 18 | GETCLOSESTUSERBYPOS |
Retrieve the name of the user closest to the position specified by Latitude and Longitude, optionally filtered by profile role and profile level. Return: A string containing the name of a user if OK, else an empty string (invalid arguments, no user matches criteria, no position information available). |
Syntax 15
StrVal = GEOLOCATION (Mode, ZoneId);
Return type: STR.
Execution
|
Mode |
Mnemonic |
Action |
| 19 | GETZONEPOSITION |
Retrieve the position of the zone ZoneId. Return: The zone position as a Position formatted string if OK, else an empty string (invalid arguments). |