<html>
<head>
<title>Jam Example</title>
<style TYPE="text/css">
<!--
BODY {font: 12px/16px verdana, arial, sans-serif !important;
text-align: left;
margin-left: 2cm;
color:#000000 !important;}
.cell {font: 12px/16px verdana, arial, sans-serif !important;
text-align: left;
color:#000000 !important;}
TD {font: 12px/16px verdana, arial, sans-serif !important;
text-align: left;
color:#000000 !important;}
H1 {font: 18px/18px verdana, arial, sans-serif !important;
text-align: left;
color:#333333 !important;}
H2 {font: 18px/18px verdana, arial, sans-serif !important;
text-align: left;
color:#333333 !important;
font-weight: bold;
margin-bottom: 14px}
H3 {font: 14px/14px verdana, arial, sans-serif !important;
text-align: left;
color:#333333 !important;
font-weight: bold;
margin-bottom: 14px}
pre {
border-right: #646464 1px solid;
padding-right: 0.5em;
border-top: #646464 1px solid;
padding-top: 0.5em;
border-left: #646464 1px solid;
padding-left: 0.5em;
border-bottom: #646464 1px solid;
padding-bottom: 0.5em;
white-space: pre;
background-color: #f6e6e6;
color: black;
margin-left: 1em;
width: 90%;
display: table;
font-size: 100%;
}
-->
</style>
</head>
<body>
<h1><a name="top"></a>P4VB - COM Interface to Perforce C++ API on Windows</h1>
<p>p4vb is contributed by <a href="http://public.perforce.com/guest/robert_cowham/pcp.html"> Robert Cowham</a> of
Vaccaperna Systems Ltd.</p>
<p>See the paper I presented at the Perforce User Conference in 2001:
<a href="http://www.perforce.com/perforce/conf2001/index.html#myth">Adventures
in API Land</a> for an overview of the API and how I use it. In particular pay
attention to the section on error handling!</p>
<p>This DLL is part of
<a href="http://www.perforce.com/perforce/products/plugins-ofc.html">P4OFC - the
integration between Microsoft Office and Perforce</a> and thus is stable and
tested.</p>
<h2>Compiler</h2>
<p>This COM DLL has been built with MS VC++ 6.0 (SP5). Future versions will be
built with VC++ 7.0.</p>
<p>Use either of the project settings:</p>
<ul>
<li>Debug</li>
<li>Release Min Dependency</li>
</ul>
<h2 ALIGN="LEFT">Main Interface Function</h2>
<p ALIGN="LEFT">The IDL definition for the main function is:</p>
<pre>[
entry("p4run"),
helpstring("runs a p4 command 'cmd' returning values in 2 output arrays"),
]
Long p4run([in] BSTR cmd,
[out] ArrayString infoArray,
[out] ArrayString errorArray,
[out] BSTR * TextFileName,
[out] BSTR * BinaryFileName);
</pre>
<p>This function allows you to execute a simple Perforce command (e.g. "info" or
"edit //depot/fred.txt") and obtain the results text.</p>
<p>Note that the command will pick up Perforce environment information in the
the normal way - so global settings are used, or P4CONFIG settings are used.
Make sure the current directory where your code is executing is set
appropriately.</p>
<h2>Examples</h2>
<p>As an example of using it, in a VB project, make sure you have set a
reference to COM object "Perforce interface for VB (plus utilities)".</p>
<p>You can then execute a simple command such as "p4 info":</p>
<pre>Dim p4cmd As String
Dim result As Long
Dim TextArr() As String
Dim InfoArr() As String
Dim ErrorArr() As String
Dim TextFileName As String
Dim BinaryFileName As String
' Need to initialise as otherwise VB kindly passes in a NULL pointer.
TextFileName = "temp"
BinaryFileName = "temp"
p4cmd = "info"
result = p4run(p4cmd, InfoArr, ErrorArr, TextFileName, BinaryFileName)
' Display the results
Dim i as integer
For i = LBound(InfoArr) To UBound(InfoArr)
ResultBox.AddItem InfoArr(i)
Next
</pre>
<p ALIGN="LEFT">This assumes a Listbox called ResultBox.</p>
<p ALIGN="LEFT">Another example shows how to access the contents of a particular
file:</p>
<pre>Dim p4cmd As String
Dim result As Long
Dim TextArr() As String
Dim InfoArr() As String
Dim ErrorArr() As String
Dim TextFileName As String
Dim BinaryFileName As String
' Need to initialise as otherwise VB kindly passes in a NULL pointer.
TextFileName = "temp"
BinaryFileName = "temp"
p4cmd = "print " & Chr(34) & DocPathname & "#" & ver & Chr(34)
result = p4run(p4cmd, InfoArr, ErrorArr, TextFileName, BinaryFileName)
</pre>
<p ALIGN="LEFT">This will print the results of the file into the temporary file
in either TextFileName or BinaryFileName from which it can be further processed.</p>
<h3 ALIGN="LEFT">Example VB Form</h3>
<p ALIGN="LEFT">A very simple VB form project is to be found here:
<a href="p4vbTestForm.txt">p4vbTestForm.txt</a> - change the file extension to .frm
and import into a new VB project and try executing a few commands.</p>
<h2 ALIGN="LEFT">Other Functions</h2>
<p ALIGN="LEFT">There are currently the following other functions implemented in
the DLL:</p>
<h3 ALIGN="LEFT">p4runstat</h3>
<pre>[
entry("p4runstat"),
helpstring("runs a p4 command 'cmd' returning values in 2 output arrays (with OutputStat option)"),
]
Long p4runstat([in] BSTR cmd,
[out] ArrayString infoArray,
[out] ArrayString errorArray,
[out] BSTR * TextFileName,
[out] BSTR * BinaryFileName);
</pre>
<p ALIGN="LEFT">This command is the same as p4run except that it turns on
perforce tagging which means that all output is prefixed bye "info:" or "error:"
as appropriate. This is the same as running "p4 -s <command>" from the
command line.</p>
<h3 ALIGN="LEFT">p4ServerVersion</h3>
<pre>[
entry("p4ServerVersion"),
helpstring("returns version of the p4d server last talked to"),
]
Long p4ServerVersion();
</pre>
<p ALIGN="LEFT">This command returns a magic number which identifies different
versions of the Perforce server (note you need to have executed at least one
command for the information to be accurate).</p>
<p ALIGN="LEFT">The meaning of the magic numbers is information you will have to
ask Perforce about!</p>
<h3 ALIGN="LEFT">p4GetPort</h3>
<pre>[
entry("p4GetPort"),
helpstring("returns value of P4PORT"),
]
BSTR p4GetPort();
</pre>
<p ALIGN="LEFT">This returns the string value for P4PORT - useful if the p4
commands are returning errors and you want to tell the user to check if the
server is up and running.</p>
<h3 ALIGN="LEFT">p4Submit</h3>
<p ALIGN="LEFT">This is its own COM object which allows you to access and modify
various parts of a changelist before a submit, and then actually do the submit.</p>
<pre>[helpstring("method Info")] HRESULT InfoArray([out] ArrayString InfoArray);
[helpstring("method Error")] HRESULT ErrorArray([out] ArrayString ErrorArray);
[propget, helpstring("property Files")] HRESULT Files([out, retval] ArrayString Val);
[propput, helpstring("property Files")] HRESULT Files([in] ArrayString newVal);
[propget, helpstring("property Jobs")] HRESULT Jobs([out, retval] ArrayString Val);
[propput, helpstring("property Jobs")] HRESULT Jobs([in] ArrayString newVal);
[helpstring("method Start")] HRESULT Start([in] long changelist);
[helpstring("method Finish")] HRESULT Finish();
[propget, helpstring("property Description")] HRESULT Description([out, retval] BSTR *pVal);
[propput, helpstring("property Description")] HRESULT Description([in] BSTR newVal);
</pre>
<p ALIGN="LEFT">First create an object, and then call the Start method,
specifying 0 for the default changelist, or alternatively the number.</p>
<p ALIGN="LEFT">You can then get and set the various properties such as a list
of Files, list of Jobs, or the Description.</p>
<p ALIGN="LEFT">Finally do the submit with the Finish method, and check the
results by calling InfoArray and ErrorArray.</p>
<p ALIGN="LEFT">As an example:</p>
<pre>Dim s as p4Submit
Dim FileList() As String
set s = new p4Submit
s.Start 0 ' Default changelist
MsgBox "Description is:" & s.Description
s.Description = "My new description"
FileList = s.Files
' Remove a file just to show we can reset the list
If UBound(FileList) - LBound(FileList) > 1 Then
FileList.RemoveItem 1
End If
s.Files = FileList
s.Finish
s.InfoArrary InfoArr
s.ErrorArray ErrorArr
' Display the results as before
</pre>
<p ALIGN="LEFT"> </p>
<p>
<a href="#top">Top</a>
</p>
</body>
</html>