PDS Methods XML

The PDS exposes an API for accessing portfolio data from Microsoft Office Project Server 2003. The API methods enable your client application to perform operations such as checking out projects and resources. The PDS API is defined using XML. (See the XML Developer Center on MSDN for more information on XML.) Because XML is a platform-independent language, you can develop client applications to access Project Server data in practically any environment.

Another advantage of an XML-based API is that it is easily readable and provides flexibility for adding or omitting parameters, thus providing a way to filter returned information. A PDS method call takes the following form:

<Request>
    <MethodName>
        <Parameter1>value</Parameter1>
        <Parameter2>value</Parameter2>
        ...
        <ParameterN>value</ParameterN>
    </MethodName>
</Request>

Every PDS method call contains a parent element named Request. The Request element contains a child element, which is the name of the method. For some methods, this element may be all that is needed to make a successful method call. For example, the PDSInfo method is called using the following XML:

<Request>
   <PDSInfo/>
</Request>

Notice that for empty elements, you can omit the start tag. If you need to specify parameters for the method call, each parameter is a child element of the method name element. For example, the following call to ProjectsAccess has four parameters:

<Request>
   <ProjectsAccess>
      <Mode>0</Mode>
      <SPID>58</SPID>
      <SPIDTimestamp>20011017105500</SPIDTimestamp>
      <Project>
         <ProjectID>3</ProjectID>
      </Project>
   </ProjectsAccess>
</Request>

The parameters themselves can contain child elements to further qualify that parameter. In this example, the Project parameter contains a ProjectID.

Request Errors

• A request returns an error if a parameter value includes characters that can be interpreted as XML tag or attribute delineators. For example, there are many requests such as ProjectsAccess that accept the parameter ProjectName or ProjectID. These requests will return a STATUS error code 4 if ProjectName includes any of the characters: & " < >. These characters should be encoded in the ProjectName value as, respectively: &amp; &quot; &lt; &gt;. Otherwise, use ProjectID instead of ProjectName.
• If any parameters are optional, they should be included in the request only if they contain data. If a request includes a parameter that does not contain data, the PDS returns an error code in the STATUS field. The error may be code 501 (rsCodeTypeInvalid), or code 38 (rsDecodeInvalidBool) if the parameter is a Boolean value (0 or 1). For example, the CodeType parameter is optional in the EnterpriseOutlineCodes request. The following request returns error 501:

<Request>
   <EnterpriseOutlineCodes>
      <CodeType/>
   </EnterpriseOutlineCodes>
</Request>

Return Values

The return value from a method call echoes the method call itself and takes the following form:

<Reply>
    <HRESULT>0</HRESULT>
    <STATUS>0</STATUS>
    <UserName>Administrator</UserName>
    <MethodName>
        method-specific output
    </MethodName>
</Reply>

The return value is contained in a parent element named Reply. All PDS methods return the HRESULT and STATUS elements, which indicate whether the call succeeded. A successful method call returns 0 for both elements; otherwise, error codes provide more information on why the call failed.

The UserName element is always returned, which is the name of the logged-on user of the client application. The Reply element contains a child element, which is the name of the method. Some methods return additional information as values in children of the MethodName element.

For example, the PDSInfo method returns the following information:

<Reply>
   <HRESULT>0</HRESULT>
   <STATUS>0</STATUS>
   <UserName>Administrator</UserName>
   <PDSInfo>
      <ExeName>PDS</ExeName>
      <CompanyName>Microsoft Corporation</CompanyName>
      <FileDescription>Microsoft Project Data Service</FileDescription>
      <Comments/>
      <ProductName>Microsoft Project Server</ProductName>
      <Title>PDS</Title>
      <LegalCopyright>Copyright © 2000-2001 Microsoft
         Corporation.</LegalCopyright>
      <LegalTrademarks/>
      <Major>1</Major>
      <Minor>0</Minor>
      <Revision>728</Revision>
   </PDSInfo>
</Reply>

In your applications, the XML requests and return values are strings. You can parse return values with string functions to get the information you require. However, in most cases, it is simpler to use the Document Object Model (DOM). The DOM is an object model that exposes the contents of an XML document and presents an easily processed standardized interpretation of an XML document to applications. You use the XML DOM by creating an instance of an XML parser. More information about using the DOM and the Microsoft XML Parser (MSXML) can be found at the XML Developer Center on MSDN. You can also refer to Programmatic Logon to Project Server, which discusses sample code that uses MSXML to extract cookie information from the XML that is returned from a logon to Project Server.