SPWeb ProcessBatchData – Display method

Basically all methods of the deprecated WSS RPC Protocol (MSDN) can be invoked via the SPWeb’s ProcessBatchData method. Since there’s little to no documentation regarding most of the RPC methods as to their usage directly with ProcessBatchData we can suspect that their support may be dropped in the new SharePoint 2010 (we still have to see how much of the CAML will be thrown out of it, and we’re talking about some really ancient stuff which’s been around since the times of the SharePoint Team Services). Most of the RPC methods were designed to serve specific tasks in the old STS but with the developing of the SharePoint object model most of these could now be much easier carried out with the latter. But … the thing is that even now in SharePoint 2007 the RPC methods are left intact and the ProcessBatchData is advertised as a faster method for inserting, updating and deleting (at least for that, but this may be true for other usages as well) of multiple list items than the standard SPListItem object model implementation.

So, let’s have a look at the Display method. A sample XML for calling it may look like this:

<?xml version="1.0" encoding="UTF-8"?>

<ows:Batch OnError="Continue">

  <Method ID="0">

    <SetList Scope="Request">702f059d-71f2-4f78-a41a-48978d381948</SetList>

    <SetVar Name="Cmd">Display</SetVar>

    <SetVar Name="XMLDATA">TRUE</SetVar>

    <SetVar Name="View">{FF964526-BBFA-4500-A43C-F4B7785E5F71}</SetVar>

  </Method>

</ows:Batch>

The SetList element contains the SPList ID, the Cmd SetVar – the method’s name. The XMLDATA SetVar parameter is actually mandatory but even if its value is FALSE the output of the method will be in XML format, not an HTML presentation of the list data. The View SetVar parameter is not mandatory – if it is not present, the default view of the list will be used, but the GUID format is important here – it should be with curly braces and uppercase. The result XML from the ProcessBatchData method will look something like this:

<Results>

  <Result ID="0" Code="0">

    <xml xmlns:s='uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882'

         xmlns:dt='uuid:C2F41010-65B3-11d1-A29F-00AA00C14882'

         xmlns:rs='urn:schemas-microsoft-com:rowset'

         xmlns:z='#RowsetSchema'>

      <s:Schema id='RowsetSchema'>

          <!-- schema data removed for brevity -->

      </s:Schema>

      <rs:data>

        <z:row ows_LinkTitle='some item' ows_fdate='2009-06-08 04:15:00' ows_flookup='1;#first' ows__UIVersionString='46.0' ows__ModerationStatus='2' ows_Editor='1;#Stefan Stanev' ows__Level='2' ows_ID='1' ows_owshiddenversion='104' ows_UniqueId='1;#{D2D82ED2-CBE7-4A56-84EC-3502FB8C2611}' ows_FSObjType='1;#0' ows_Created_x0020_Date='1;#2009-06-07 11:03:04' ows_Created='2009-06-07 11:03:04' ows_FileLeafRef='1;#1_.000' ows_FileRef='1;#sites/1/Lists/somelist/1_.000' />

        <z:row ows_LinkTitle='another item' ows_flookup='4;#one;more' ows__UIVersionString='22.0' ows__ModerationStatus='2' ows_Editor='1;#Stefan Stanev' ows__Level='2' ows_ID='2' ows_owshiddenversion='56' ows_UniqueId='2;#{9C1D1419-742A-41DC-85E1-1B1E7A50A2C8}' ows_FSObjType='2;#0' ows_Created_x0020_Date='2;#2009-06-07 11:03:27' ows_Created='2009-06-07 11:03:27' ows_FileLeafRef='2;#2_.000' ows_FileRef='2;#sites/1/Lists/somelist/2_.000' />

      </rs:data>

    </xml>

  </Result>

</Results>

The XML schema of the result (the part within the corresponding Result element) is actually identical to the XML schema of the result of the GetListItems method of the standard Lists web service (though the former is generated in the COM owssvr.dll library and the latter in the Microsoft.SharePoint.dll assembly with managed code – in the getter of the SPListItemCollection.Xml property). The result XML contains the data of all fields in the specified view plus several system fields and the returned items are sorted and filtered in accordance with the view’s query settings.

Several additional SetVar parameters can be used for simple filtering and sorting of the returned result set – basically these are the same that appear as query parameters when you sort or filter list views in the SharePoint UI – e.g. SortField, SortDir, FilterField1, FilterValue1, FilterField2, FilterValue2, RootFolder:

    <SetVar Name="SortField">Title</SetVar>

    <SetVar Name="SortDir">Desc</SetVar>

    <SetVar Name="FilterField1">Title</SetVar>

    <SetVar Name="FilterValue1">another</SetVar>

    <SetVar Name="RootFolder">/sites/1/Lists/somelist/fldr1/f1</SetVar>

If you use the RootFolder parameter with * as value you will get all items in the list recursively.

There is yet another optional SetVar parameter that can be used with the Display method – the Query parameter. Despite its name, you cannot specify a view CAML query in it, but just a list of field names, separated with spaces – basically with it you can specify the view fields that will appear in the result (the extra system fields will appear too). An unpleasant side effect of using it is that it effectively overrides the specified view’s query settings – so you end up with an unfiltered and unsorted result set – the effect of the SortField, FilterField1, etc SetVar-s (if present) is not affected though. A sample usage of the Query parameter (the asterisk – * – value can be used here as well):

    <SetVar Name="Query">ID Title</SetVar>

So, the conclusion about the Display ProcessBatchData method is that it is yet another way to retrieve SharePoint list item data, though it is not as flexible as the other mechanisms for list item data fetching – at least in respect to the query options that can be used for filtering and sorting the result set. One advantage though may be that like the other ProcessBatchData methods it can be executed in batches – so with one call of the ProcessBatchData method you will be able to retrieve the data from several lists.