ReadMultiple Operation

Microsoft Dynamics Nav 2009

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.

NoteNote

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.

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 entire set of results, set setSize to zero.

To reverse the order of the results, set setSize to negative.

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.

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.

Retrieving Last Page

To retrieve the last record of a page, set setSize to -1. Using negative numbers in setSize will sort 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 within 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 Microsoft Dynamics NAV style filter that is specified in a standard Microsoft Dynamics NAV filter format.

The following example returns the first 100 customer names that start with an S. For a detailed code example, see Walkthrough: Registering and Consuming a Page Web Service.

C#
Copy 
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:

C#
Copy 
Customer_Service service = new Customer_Service();
service.UseDefaultCredentials = true;

const int fetchSize = 10;
string bookmarkKey = null;
List<Customer> customerList = new List<Customer>();

// Read 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);
}

// Print the collected data.
foreach (Customer customer in customerList)
{
    Console.WriteLine(customer.Name);
}

Community Additions

ADD
Show: