| [in] usn | The user-name that you need to use to authenticate on this interface. |
| [in] pwd | The password that you need to use to authenticate on this interface. |
| [in] requestedRowNumber | The number of rows that you would prefer to get in one set. |
| [in] columns | String array of the requested columns. For the full list of supported columns please refer to the Database API Documentation. If a non-existing column is requested then that column will appear in the returned XML and every entry in that column will be an empty string. |
| [in] earliestServerTimeStamp | The ServerTimeStamp for and after which you would like to retrieve the data. Please make sure that you specify the time in utc. The earliestServerTimeStamp is used so we can figure out what the startRowId would be for the first call. Without it if you needed data from yesterday and then always going forward, you would have difficulties deciding what startRowId to pass in for the first call that would match the rowid of the first row generated yesterday. |
| [in] startRowId | The ID of the last entry in the last chunk. If this is the first chunk then make it -1. See "Retrieving large amount of data" in the Remarks section for more details. |
| [in] options | For future use. For now it must be null or empty. |
| [out] lastRowId | The rowid of the last entry in the chunk. Use this value as startRowId to query the following set of rows for the same query. |
| [out] errorMsg | If an error happpens this string contains the error message. In case an error has happened (this variable contains a valid non-empty string) then the return value will not contain any usable data, do not try to parse it as an xml. |
| [out] ajustedRowNumber | Under some circumstances it might happen that the web-service cannot use the requestedRowNumber to execute the query therefore it needs to adjust it. This value reveals the real row number that was used to perform the query. For more information see "Retrieving large amount of data" in the remarks. |
| return value |
If the errorMsg variable is null or empty then the returned string contains the
requested data in xml format. The xml has the following structure:
<?xml version="1.0" encoding="utf-16"?>
Please note this.
<root> <EX_TemperatureReadings> <row ID="1133605" VehicleID="26" VehicleName="369998" VehicleTypeID="3" FridgeInfoTimeStamp="2011-03-31 02:59:02Z" ServerTimeStamp="2011-03-31 03:00:08Z" FridgeOn="False" TrackerDoorSwitch1Open="" TrackerDoorSwitch2Open="" Zone1Setpoint="" Zone1Return="" Zone2Setpoint="" Zone2Return="" Zone3Setpoint="" Zone3Return="" FridgeEngineModeOn="" FridgeCycleSentryOn="" Zone1On="" Zone2On="" Zone3On="" DoorSwitch1Open="" DoorSwitch2Open="" DoorSwitch3Open="" FuelLevel="" BatteryVoltage="" Sensor1="-23.21875" Sensor2="-20.5625" Sensor3="" Sensor4="" Sensor5="" Sensor6="" Zone1Discharge="" Zone2Discharge="" Zone3Discharge="" /> <row ID="1133612" VehicleID="4" VehicleName="TX99" VehicleTypeID="1" FridgeInfoTimeStamp="2011-03-31 02:07:34Z" ServerTimeStamp="2011-03-31 03:00:34Z" FridgeOn="False" TrackerDoorSwitch1Open="" TrackerDoorSwitch2Open="" Zone1Setpoint="" Zone1Return="" Zone2Setpoint="" Zone2Return="" Zone3Setpoint="" Zone3Return="" FridgeEngineModeOn="" FridgeCycleSentryOn="" Zone1On="" Zone2On="" Zone3On="" DoorSwitch1Open="" DoorSwitch2Open="" DoorSwitch3Open="" FuelLevel="" BatteryVoltage="" Sensor1="" Sensor2="" Sensor3="" Sensor4="" Sensor5="" Sensor6="" Zone1Discharge="" Zone2Discharge="" Zone3Discharge="" /> </EX_TemperatureReadings> </root> |
0.726
This function will only return data that was saved after the database version was upgraded
to the above mentioned version.
You cannot use this function to retrieve infinitely large amount of data in one call. In case you would like to get a large set of rows you will need to call this function several times. You can specify your preference about the number of rows returned in one function-call in requestedRowNumber. If it is possible the webservice will use this number, but there are circumstances in which the webservice needs to adjust this number for performing the query. The real row number that was used for performing the query is retuned in ajustedRowNumber.
To find out whether there is more data that was not returned with the previous call you should compare ajustedRowNumber with the number of rows in the returned xml. If these two numbers match then it is likely that there are more rows to return. If the number of rows in the returned xml is smaller than ajustedRowNumber then most probably you have retrieved all the data for now. No new rows will be returned until new data gets saved.
If you want to fetch the next set of data, you need to remember the value of lastRowId from the last call and pass that value in as startRowId to query the following set of rows.
The order of returned rows is not guaranteed; the order of the rows matches the order in which they were saved into the database. In case the system time of the operating system that hosts the database server has been adjusted the order of ServerTimestamp might not match the order the rows were saved. For similar reasons it is not guaranteed that you do not get entries older than the time that you specify in earliestServerTimeStamp.
Please see this page.