xml.html #1

<TITLE>XML Output</TITLE>

<h2>Requesting XML output from P4Web</h2>
P4Web normally returns results as HTML. However, you can direct P4Web to return results encoded as XML, as follows.
<h3>In a browser</h3>
<P>To direct P4Web to return output in XML format to a browser:
<ol>
  <li>To display the P4 command field, click <img src= "/p4cmd?icon"> .</li>
  <li>In the P4 command field, type the desired command and click the XML radio 
    button.</li>
  <li>Click Go. XML output for the specified command is displayed in the browser.</li>
</ol>

<h3>From a script</h3>
<P> To request XML output from P4Web using a script, specify <a href="actioncodes?help">action 
  code</a> 201 in the URL that you submit. The following example shows how to 
  request XML output in a Perl script using the standard LWP module to issue a 
  web request. P4Web returns its XML output into the variable <tt>$page</tt>. 
  The example request issues the <tt>p4 changes</tt> command to obtain detailed 
  information about changelists, limiting the output to 50 changelists using the 
  <tt>-m</tt> flag. 
<pre> use LWP::Simple; </pre>
<pre> my $url = 'http://myserver.perforce.com:8080/p4%20changes%20-m%2050%20-l?ac=201';  </pre>
<pre> my $page = get $url; </pre>
When developing scripts, use the browser to display the XML results, to help you 
determine the output that your script must parse. 
<h2>Format of P4Web's XML Output</h2>

<P>PWeb's XML output is formatted as follows: 
<p> 
  
<ul>
  <li>All tag names and attributes are lower case. 
    <p> 
  <li>The first tag returned is a <tt>&lt;perforce ... &gt;</tt> header tag, which 
    has the following attributes: 
    <p> 
    <table border="1" cellpadding="1">
      <tr> 
        <td><b>Attribute</b></td>
        <td><b>Description</b></td>
      </tr>
      <tr> 
        <td><tt>command</tt></td>
        <td>The p4 command for which output is returned</td>
      </tr>
      <tr> 
        <td><tt>server</tt></td>
        <td>The host and port of the server that executed the command</td>
      </tr>
      <tr> 
        <td><tt>user</tt></td>
        <td>Perforce username</td>
      </tr>
      <tr> 
        <td><tt>client</tt></td>
        <td>Client workspace name</td>
      </tr>
      <tr> 
        <td><tt>time</tt></td>
        <td>The date and time the XML output was generated (in local P4Web time) 
          <b>Format</b>: <i><tt>Day, DD MMM YYYY HH:MM:SS TMZ</tt></i></td>
      </tr>
    </table>
    <br>
    <b>Example</b> of a perforce header: 
    <pre>&lt;perforce<br>    command=&quot;filelog&quot;<br>    server=&quot;perforcehost:2000&quot;<br>    user=&quot;mrp4&quot;<br>    client=&quot;mrp4_win-mrp4&quot;<br>    time=&quot;Wed, 11 Jun 2008 10:30:17 PDT&quot;&gt; </pre>
    <p> 
  <li>If the command returnes a specification (for example, <tt>p4 client -o</tt>), 
    a specdef tag follows the header and encloses the unparsed specification. 
    <p><b>Example: </b><tt>&lt;specdef&gt;Client;code:301;rq;ro;seq:1;len:32;;Update;code:302;...;;LineEnd;code:310;type:select;fmt:L;len:12;val:local/unix/mac/win/share;;View;code:311;type:wlist;words:2;len:64;;&lt;/specdef&gt;</tt> 
    <p> 
    <p> 
  <li>Following the header tag (and the specdef tag, if present), is the command 
    tag, which encloses all remaining output. 
    <p> <b>Example</b>: 
    <p> 
    <pre>&lt;filelog&gt; <br>&nbsp;&nbsp;&nbsp;[remaining output]     <br>&lt;/filelog&gt;</pre>
  <li>Recurring items are formatted to wrap all occurrences inside a single tag. 
    For example, multiple file revisions are returned as an instance of a <tt>revs</tt> 
    tag containing multiple instances of <tt>rev</tt> tags, as shown in the following 
    example. 
    <p> <b>Example</b>: 
    <p> 
    <pre>&lt;revs&gt;

	&lt;rev value="2" id1="0"&gt;
		&nbsp;...
	&lt;/rev&gt;

	&lt;rev value="1" id1="1"&gt;
		&nbsp;...
	&lt;/rev&gt;

&lt;/revs&gt;</pre>
  <li>Each instance of a recurring tag is assigned an ID number, using its id1 
    attribute. 
    <p> <b>Example</b>: 
    <pre>&lt;rev<br>    value=&quot;20&quot;<br>    id1=&quot;44&quot;&gt;<br>        &lt;change&gt;5592&lt;/change&gt;<br>        &lt;action&gt;edit&lt;/action&gt;<br>        &lt;type&gt;text&lt;/type&gt;<br> &lt;/rev&gt; </pre>
    <p> 
  <li>If a recurring tag contains its own recurring tags, they are assigned an 
    ID number using the id2 attribute. 
    <p> <b>Example</b>: 
    <pre>
	&lt;rev value="21" id1="43"&gt;
		&lt;change&gt;5615&lt;/change&gt;

		...
		&lt;desc&gt;Add some examples with spaces in their names&lt;/desc&gt;
		&lt;hows&gt;
			&lt;how value="branch into" id1="43" id2="0"&gt;
				&lt;file&gt;//depot/testing/job011981/Case/BranchView.cpp&lt;/file&gt;

				&lt;srev&gt;#none&lt;/srev&gt;
				&lt;erev&gt;#1&lt;/erev&gt;
			&lt;/how&gt;
			&lt;how value="branch into" id1="43" id2="1"&gt;
				&lt;file&gt;//depot/testing/job011981/Case/dir/BranchView.cpp&lt;/file&gt;

				&lt;srev&gt;#none&lt;/srev&gt;
				&lt;erev&gt;#1&lt;/erev&gt;
			&lt;/how&gt;
		&lt;/hows&gt;
	&lt;/rev&gt;
</pre>
</ul>
    <p> 
  
<li>Informational output is enclosed in identifying tags, in the following format: 
  <pre>	&lt;error&gt;<i>Error text...</i>&lt;/error&gt;</pre>
  <pre>	&lt;data&gt;<i>Data message...</i>&lt;/data&gt;</pre>
  <pre>	&lt;info&gt;<i>Informational message...</i>&lt;/info&gt;</pre>
  <p> 
<li>Data that contains a line-feed, TAB or space-space is tagged as CDATA to preserve 
  white space characters. CDATA is always uppercase. 
  <blockquote>
    <p><b>Example</b>: <tt>&lt;![CDATA[name: Mike email: tomb@mydata.selmatter@us.oracle.com]]&gt; 
      </tt></p>
  </blockquote>
</li>