actioncodes.html #1

<TITLE>P4Web User Guide - P4Web URL Reference</TITLE>

      <p>You can link to Perforce depot information from within your own HTML 
        documents by constructing URLs that direct P4Web to return specified data. 
        Such URLs can be used in email, in web pages (static or CGI-generated), 
        and in any context where URLs are useful. You can create scripts that 
        construct such URLs and pass them to a Web browser, enabling users to 
        display Perforce information without requiring them to install Perforce 
        client applications on their computer. In constructing the URLs, use the 
        same options and flags that you use on the command line. </p>
      <p>Some simple examples: </p>
    
<table  border="1" cellpadding="1">
  <tr>
    <td>Display the file <tt>//depot/main/atlas/readme.txt</tt> </td>
    <td><tt>http://myp4web:8080/depot/main/atlas/readme.txt</tt></td>
  </tr>
  <tr>
    <td>List the files in <tt>//depot/main/atlas</tt></td>
    <td><tt>http://myp4web:8080/depot/main/atlas/</tt></td>
  </tr>
  <tr> 
    <td  >Display the depot root for the  server to which P4Web is connected </td>
    <td ><tt>http://myp4web:8080/</tt></td>
  </tr>
  <tr> 
    <td>List the executable files (files with a <tt>.exe </tt>extension) in a specified folder</td>
    <td> <tt>http://myp4web:8080//depot/main/binaries/windows/*.exe</tt> </td>
  </tr>
  <tr> 
    <td> Display a file as it appeared on a specified date </td>
    <td><tt>http://myp4web:8080//depot/www/sitemap.html@2004/1/1</tt></td>
  </tr>
</table>

<h3>URL Syntax</h3>

      The syntax for P4Web URLs is as follows: 
      <blockquote> 
        <p><tt>http://<em>p4webhostname</em>:<em>port</em>/[@<em>parameters</em>@][/]/<em>object</em>[[?ac=<em>n</em>][&amp;<em>parameters</em>]]</tt> </p>
      </blockquote>
      <p>P4Web uses a variety of other elements in the URLs that it constructs, 
        but you can omit these elements in the URLs that you construct for your 
        queries. The basic elements of URLs for P4Web are as follows.</p> 
<table   border="1" cellpadding="1">
  <tr> 
    <td> 
      <h3>Element</h3>    </td>
    <td> 
      <h3>Description</h3>    </td>
  </tr>
  <tr> 
    <td><tt>http://<i>p4webhostname</i>:<i>port</i>/</tt> </td>
    <td>The P4Web server and port</td>
  </tr>
  <tr> 
    <td><tt><i>parameters</i></tt> </td>
    <td><p>A list of<tt><em> arg</em>=<em>value</em></tt> pairs separated by &ldquo;&amp;&rdquo;: <em><tt>arg</tt></em><tt>=<em>value</em>[&amp;<em>arg</em>=<em>value</em>]</tt></p>
    <p>Parameters can be specified before or after the object. If you specify parameters before the object, delimit the parameters with &quot;at&quot; signs (@). If you specify parameters after the object, precede the list of parameters with a question mark (?). The parameter syntax is the standard format for URL queries.</p>    </td>
  </tr>
  <tr> 
    <td><tt><em>object</em></tt></td>
    <td>Depot file, spec name (for example, job, user, label, etc.), or a P4 command. If you omit the action code, the object is interpreted as a depot path specifying a file or folder. The parameter list can include an action code.</td>
  </tr>
  <tr> 
    <td><tt>ac=<i>n</i></tt> </td>
    <td>(optional) Action code, preceded by &quot;?&quot; (that is, formatted as <tt>GET</tt> data). Specify the action code in the list of parameters as described above.</td>
  </tr>
</table>
<p>To specify a folder or file that resides in the Perforce server, use the following syntax:</p>
<blockquote>
  <p><tt>//<em>depot_path</em>/[@<em>revision_specifier</em>]</tt></p>
</blockquote>
<p>where 
  <tt>//<i>depot_path</i>/</tt> specifies the  file or folder and 
  <tt><em>revision_specifier</em></tt>  is a changelist number, label, 
or date in <tt>yyyy/mm/dd</tt> format. The depot path can be preceded by a single slash or the Perforce standard double slash.</p>
<p>To specify special-purpose characters in URLs, use the standard escape sequence <tt>%<em>hex-value</em></tt>. You must escape the following special-purpose characters:</p>
<ul>
  <li># </li>
  <li>?</li>
  <li>&amp;</li>
  <li>=
  </li>
</ul>
<p>For example, to display a list of 
  labels owned by user <tt>bruno</tt>, you can create a URL that includes the <tt>p4 labels</tt> command. The following URL uses the <tt>%20</tt> escape sequence to specify the spaces required to separate the syntactic elements of the command:</p>
<blockquote>
  <p> <tt>http://myserver.perforce.com/p4%20labels%20-u%20bruno?ac=201</tt>
  </p>
</blockquote>
<h3>Action Codes
</h3>
<p>The following table lists the action codes that are supported for P4Web URLs. 
  There are no action codes for commands that require administrator privileges.</p>
<table border="1" >
  <tr> 
    <td > 
      <h3>Type</h3>    </td>
    <td > 
      <h3>Description</h3>    </td>
    <td > 
      <h3>Action<br>
        Code</h3>    </td>
  </tr>
  <tr> 
    <td rowspan="3"><b>Branches</b></td>
    <td nowrap > 
      <p>Display view for a specified branch specification</p>
      <p><b>Example:</b><tt> http://myp4web:8080/talkhouse1.0?ac=14</tt></p>    </td>
    <td >14</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>Compare branched source and target files using a branch specification</p>
      <p><b>Example:</b><tt> http://myp4web:8080/talkhouse1.0?ac=126</tt></p>    </td>
    <td >126</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>List branch specifications</p>
      <p><b>Example:</b><tt> http://myp4web:8080/?ac=82</tt></p>    </td>
    <td >82</td>
  </tr>
  <tr> 
    <td rowspan="4"><b>Changelists</b></td>
    <td nowrap > 
      <p>Display detail for specified changelist</p>
      <p><b>Example:</b><tt> http://myp4web:8080/799?ac=10</tt></p>
      <p>&nbsp;</p>    </td>
    <td >10</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>List all submitted changelists for specified path</p>
      <p><b>Example:</b><tt> http://myp4web:8080//depot/Talkhouse/rel1.0/?ac=43 
        </tt></p>    </td>
    <td >43</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>Display fixes for a specified changelist</p>
      <p><b>Example:</b><tt> http://myp4web:8080/799?ac=133</tt></p>    </td>
    <td >133</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>Display submitted changelists containing specified file</p>    
    <p><b>Example:</b><tt> http://myp4web:8080//depot/Jam/MAIN/src/Build.com?ac=69</tt> </p></td>
    <td >69</td>
  </tr>
  <tr> 
    <td><b>Diffing</b></td>
    <td nowrap > 
      <p>Diff two file revisions</p>
      <p><b>Example:</b><tt> http://myp4web:8080//depot/main-dev/EBolt.java?ac=19&amp;rev1=1&amp;rev2=2</tt></p>
      <p>or:</p>
      <p><tt>http://myp4web:8080/@rev1=1&amp;rev2=2@//depot/main-dev/EBolt.java?ac=19</tt></p></td>
    <td >19</td>
  </tr>
  <tr> 
    <td rowspan="6"><b>Files</b></td>
    <td nowrap > 
      <p>List files in specified path matching specified pattern (including wildcards)</p>
      <p><b>Example:</b><tt> http://myp4web:8080/@pat=*.java@//depot/Talkhouse/main-dev/?ac=30</tt></p>    </td>
    <td >30</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>Display  file as plain text within an HTML document </p>
      <p><b>Example:</b><tt> http://myp4web:8080//depot/www/dev/index.html?ac=64</tt></p>    </td>
    <td >64</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>Send file contents to browser as text/plain document</p>
      <p><b>Example:</b><tt> http://myp4web:8080//depot/www/dev/index.html?ac=18</tt></p>    </td>
    <td >18</td>
  </tr>
  
  <tr> 
    <td nowrap > 
      <p>Display annotated file text</p>
      <p><b>Example:</b><tt> http://myp4web:8080//depot/www/dev/index.html?ac=193</tt></p>    </td>
    <td >193</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>Display revision history</p>
      <p><b>Example:</b><tt> http://myp4web:8080//depot/main/ProjectX/Help/roadmap.html?ac=22</tt></p>    </td>
    <td >22</td>
  </tr>
  <tr> 
    <td nowrap >
      <p> Diff a file revision against the previous revision</p>
      <p><strong>Example</strong>: <tt>http://myp4web:8080//depot/main-dev/EBolt.java?ac=185&amp;rev1=9</tt></p>    </td>
    <td >185</td>
  </tr>
  <tr><td rowspan="5"><b>Jobs</b></td> 
    <td nowrap > 
      <p>Display a list of files and folders in specified path</p>
      <p><b>Example:</b><tt> http://myp4web:8080//depot/www/dev/?ac=83</tt></p>    </td>
    <td >83</td>
  </tr>
    <tr>
    <td nowrap > 
      <p>List jobs</p>
      <p><b>Example:</b><tt> http://myp4web:8080//?ac=107</tt></p>    </td>
    <td >107</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>Display job detail</p>
      <p><b>Example:</b><tt> http://myp4web:8080/job000018?ac=111</tt></p>    </td>
    <td >111</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>Display changelists that fix a specified job</p>
      <p><b>Example:</b><tt> http://myp4web:8080/job000018?ac=135</tt></p>    </td>
    <td >135</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>Display the job specification</p>
      <p><b>Example:</b><tt> http://myp4web:8080/?ac=130</tt></p>    </td>
    <td >130</td>
  </tr>
  <tr> 
    <td rowspan="4"><b>Labels</b></td>
    <td nowrap > 
      <p>List files in a specified label</p>
      <p><b>Example:</b><tt> http://myp4web:8080/jam-1.1.0?ac=118</tt></p>    </td>
    <td >118</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>List labels</p>
      <p><b>Example:</b><tt> http://myp4web:8080//?ac=77</tt></p>    </td>
    <td >77</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>Display detail for a specified label</p>
      <p><b>Example:</b><tt> http://myp4web:8080/jam-1.1.0?ac=16</tt></p>    </td>
    <td >16</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>List labels that contain files in a specified path</p>
      <p><b>Example:</b><tt> http://myp4web:8080//depot/www/dev/?ac=127</tt></p>    </td>
    <td >
      <p>127</p>
      <p>(or use 184 to omit links)</p>    </td>
  </tr>
  <tr> 
    <td rowspan="5"><b>Reporting</b></td>
    <td nowrap > 
      <p>Display file view of server positioned as specified (<tt>to //depot</tt>, in this example).</p>
      <p><b>Example:</b><tt> http://myp4web:8080//depot/?ac=71</tt></p>    </td>
    <td >71</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>Show status of specified file (same as <tt>ac=22</tt> minus revision history)</p>
      <p><b>Example:</b><tt> http://myp4web:8080//depot/Jam/MAIN/src/Build.com?ac=104</tt></p>    </td>
    <td >104</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>List all open files (all workspaces). Be advised that this action code can return extremely large amounts of output.</p>
      <p><b>Example:</b><tt> http://myp4web:8080//?ac=62</tt></p>    </td>
    <td >62</td>
  </tr>
  <tr>
    <td nowrap >
      <p>Run a p4 command, returning output as XML.</p>
      <p><b>Example</b>: <tt>http://myhost:8080//p4%20info?ac=201</tt></p>    </td>
    <td >201</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>Display server and P4Web version info</p>
      <p><b>Example:</b><tt> http://myp4web:8080//?ac=151</tt></p>    </td>
    <td >151</td>
  </tr>
  <tr> 
    <td rowspan="2"><b>Users</b></td>
    <td nowrap > 
      <p>Display details for specified user</p>
      <p><b>Example:</b><tt> http://myp4web:8080/bruno?ac=17 </tt> </p>    </td>
    <td >17</td>
  </tr>
  <tr> 
    <td nowrap > 
      <p>List users</p>
      <p><b>Example:</b><tt> http://myp4web:8080//?ac=81 </tt> </p>    </td>
    <td >81</td>
  </tr>
</table>

<h3>Commonly-Used Parameters</h3>

      <p>P4Web uses a variety of parameters in the URLs it constructs. Many of 
        the parameters are for internal use and are not relevant for scripting. 
        To construct the precise URL for the information you seek, browse using 
        P4Web until you have the desired results displayed, then copy the URL 
        from the address bar and use it as the basis to construct your own URL. Commonly-used 
        parameters are as follows. 
    
<table  border="1" cellpadding="1">
  <tr> 
    <td width="220"> 
      <h3>Parameter</h3>    </td>
    <td width="580"> 
      <h3>Description</h3>    </td>
  </tr>
  <tr> 
    <td><tt>&amp;cd=<i>path</i></tt></td>
    <td>Path to a folder</td>
  </tr>
  <tr> 
    <td><tt>&amp;nx=<i>n</i> </tt></td>
    <td>Maximum number of items to display</td>
  </tr>
  <tr>
    <td><tt>&amp;pat=<i>file_matching_pattern</i></tt></td>
    <td>Wildcard expression for matching a set of files</td>
  </tr>
  <tr>
    <td><tt>&amp;rev1=<i>n</i>, @rev2=<em>n</em></tt></td>
    <td>Specifies a pair of revisions, for example, for diffing files</td>
  </tr>
  <tr> 
    <td><tt>&amp;sho=<i>flag</i></tt></td>
    <td>Specifies the partial results that you want returned, as described below</td>
  </tr>
  <tr> 
    <td><tt>&amp;sr=@<i>revision_specifier</i></tt></td>
    <td>A Perforce revision specifier (revision number, label, date, or changelist 
      number) </td>
  </tr>
</table>
<h3><a name="chunks" id="chunks"></a>Displaying Sections of Results Pages</h3>
<p>To display specified sections of the full-page results that P4Web normally returns, add  <tt>sho=<i>section</i>[,<i> section...</i>] </tt> parameters to 
      the URL. </p><p><strong>Example</strong>: <tt>sho=title,filter,body</tt>. This feature enables you to  embed specified portions of P4Web pages into your own web pages. </p>
<p>Valid sections are as follows: </p>

    <table border="1" cellpadding="1">
      <tr>
        <td><div align="left"><strong>Description</strong></div></td>
        <td><div align="left"><strong>Keyword</strong></div></td>
        <td><div align="left"><strong>Remark</strong></div></td>
      </tr>
      <tr>
        <td><div align="left">Perforce logo</div></td>
        <td><div align="left"><tt>logo</tt></div></td>
        <td><div align="left">&nbsp;</div></td>
      </tr>
      <tr>
        <td><div align="left">Header</div></td>
        <td><div align="left"><tt>header</tt></div></td>
        <td><div align="left">Includes logo </div></td>
      </tr>
      <tr>
        <td><div align="left">Path</div></td>
        <td><div align="left"><tt>path</tt></div></td>
        <td><div align="left">Includes logo and header</div></td>
      </tr>
      <tr>
        <td><div align="left">Tabs</div></td>
        <td><div align="left"><tt>tabs</tt></div></td>
        <td><div align="left">&nbsp;</div></td>
      </tr>
      <tr>
        <td><div align="left">Toolbar</div></td>
        <td><div align="left"><tt>toolbar</tt></div></td>
        <td><div align="left">&nbsp;</div></td>

      </tr>
      <tr>
        <td><div align="left">Title</div></td>
        <td><div align="left"><tt>title</tt></div></td>
        <td><div align="left">&nbsp;</div></td>
      </tr>
      <tr>
        <td><div align="left">Filter</div></td>
        <td><div align="left"><tt>filter</tt></div></td>
        <td><div align="left">&nbsp;</div></td>
      </tr>
      <tr>
        <td><div align="left">Body</div></td>
        <td><div align="left"><tt>body</tt></div></td>
        <td align="right"><div align="left">(Required)</div></td>
      </tr>
      <tr>
        <td><div align="left">Copyright</div></td>
        <td><div align="left"><tt>copyright</tt></div></td>
        <td><div align="left">&nbsp;</div></td>
      </tr>
</table>
   
  
<p>To ensure that any generated links in results pages return the same sections, place the <tt>sho</tt> parameter between the &quot;at&quot; signs (@) in the URL that you send to P4Web. For example:</p>
<blockquote>
  <p><tt> http://p4webhost:8080/@sho=logo,body@//?ac=83</tt></p>
</blockquote>
<p>The page returned by the preceding URL contains only the logo and body. All generated links in this results page also contain the <tt>sho=logo,body</tt> parameter and return only the logo and body when you click them. To ensure that all generated links in the results page return full pages, place the <tt>sho</tt> parameter at the end of the URL.</p>