| [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. |
| [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. |
| [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] options | String parameter. This is currently unused and reserved for future versions of the API. Pass in an empty string. |
| earliestCreationTime | The time for and after which you would like to retrieve the data. Please make sure that you specify this in utc. |
| [in] startPointGeneration | A start point expressed in terms of a generation number. For more on generation numbers and restart points, see the remarks section. |
| [out] lastGeneration | The generation number of the last entry in the returned chunk. |
| [in] requestedNumRows | Specifies how many rows to return in this "chunk." |
| [out] adjustedNumRows |
Each customer is configured with a minimum and maximum threshold. Maximum thresholds ensure no
single response becomes too large. Minimum thresholds helps prevent the server being flooded
with requests returning no data. If the client requests a number of rows outside these boundaries
the number of rows returned will be adjusted. Example: CustomerA has a minimum threshold of 100, and a maximum threshold of 1000. She sends a request for 2000 records. The adjustedNumRows will be 1000. |
| 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_RCOMInCabStops> <row VehicleID="31" StopID="545" CreationTime="2011-08-26 13:40:43Z" UserName="RCOMONLINE\mrsmith" LocationID="26999" Latitude="41.0358505415911" Longitude="-81.4796129155651" JobNumber="" Message="PICK UP WATER COLLECTORS.
CALL BEFORE LEAVING.

THANK YOU" JobOrder="0" Deleted="True" Status="18" ETA="2011-08-26 16:17:43Z" Distance="" StatusDescription="Stop deleted by driver" /> </Ex_RCOMInCabStops> </root> |
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 requestedNumRows. 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 adjustedNumRows.
To find out whether there is more data that was not returned with the previous call you should compare adjustedNumRows 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 ajustedNumRows 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 lastGeneration from the last call and pass that value in as startPointGeneration to query the following set of rows.
There is a chance that you get the same stop more than once, your application needs to be prepared to handle this case. One reason for this is a potential overlap in chunking, but also the same stop will be returned again with updated values if it is changed since you last retrieved it.
Please see this page.