ReadMultiple Operation
Reads a filtered set of records. This operation returns an array of entities. The ReadMultiple operation allows the consumer of a web service to specify the number of records to be returned at one time. This can reduce load on the server.
Note
Records on a page that were inserted after the page was retrieved are not read. Records on a page may be incorrectly included in the retrieved dataset if they were deleted after the page was retrieved.
Method Signature
Entity [] ReadMultiple(Entity_Filter[] filterArray, string bookmarkKey, int setSize)
Parameters
| Parameter | Description |
|---|---|
| filterArray | Type: Entity_Filter[] An array of record filters. |
| bookmarkKey | Type: String The last record bookmark of the page that was previously read. To return the first page of results, set bookmarkKey to NULL. |
| setSize | Type: Integer The size of the set to be returned. To return the complete set of results, set setSize to zero. To reverse the order of the results, set setSize to negative. |
Results
| Result name | Description |
|---|---|
| entity[] | Type: An array of Entities An array of a specific object type that represents the page. Contains the latest values that are present on the page. The server will return at most setSize records. If all records have been already returned, then subsequent calls will return no records (a 0-element array in C#). You should keep calling the ReadMultiple function until no records are returned. |
| entity.Key | Type: String The key of the last record read. In C#, you can access it with Entity[Entity.Length-1].Key. Pass this as bookmarkKey for the next ReadMultiple call. |
Faults
This operation does not throw faults when no matching records are present. Instead, it returns an empty record list.
Faults are possible if they are generated by the C/AL code.
Remarks
Retrieving Last Page
To retrieve the last record of a page, set setSize to -1. Using negative numbers in setSize sorts the records in descending order.
Entity_Filter
You use the Entity_Filter parameter with the ReadMultiple operation. It describes a filter that can be applied on a specific field in a record. The Entity_Filter parameter contains two members: Field and Criteria.
Field contains the name of the field that the filter is applied to. This name comes from the Entity_Fields enum.
Criteria is of type string and can contain any valid Dynamics NAV style filter that is specified in a standard Dynamics NAV filter format.
Usage Examples
The following example returns the first 100 customer names that start with an S. For a detailed code example, see Walkthrough: Registering and Using a Page Web Service (SOAP).
List<Customer_Filter> filterArray = new List<Customer_Filter>();
Customer_Filter nameFilter = new Customer_Filter();
nameFilter.Field = Customer_Fields.Name;
nameFilter.Criteria = "S*";
filterArray.Add(nameFilter);
Customer[] custList = service.ReadMultiple(filterArray.ToArray(), null, 100);
This example uses the bookmarkKey argument to read customer records in batches of 10:
Customer_Service service = new Customer_Service();
service.UseDefaultCredentials = true;
const int fetchSize = 10;
string bookmarkKey = null;
List<Customer> customerList = new List<Customer>();
// Reads customer data in pages of 10.
Customer[] results = service.ReadMultiple(new Customer_Filter[] { }, bookmarkKey, fetchSize);
while (results.Length > 0)
{
bookmarkKey = results.Last().Key;
customerList.AddRange(results);
results = service.ReadMultiple(new Customer_Filter[] { }, bookmarkKey, fetchSize);
}
// Prints the collected data.
foreach (Customer customer in customerList)
{
Console.WriteLine(customer.Name);
}