p4vb is contributed by Robert Cowham of Vaccaperna Systems Ltd.
See the paper I presented at the Perforce User Conference in 2001: Adventures in API Land for an overview of the API and how I use it. In particular pay attention to the section on error handling!
This DLL is part of P4OFC - the integration between Microsoft Office and Perforce and thus is stable and tested.
This COM DLL has been built with MS VC++ 6.0 (SP5). Future versions will be built with VC++ 7.0.
Use either of the project settings:
The IDL definition for the main function is:
[
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);
This function allows you to execute a simple Perforce command (e.g. "info" or "edit //depot/fred.txt") and obtain the results text.
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.
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)".
You can then execute a simple command such as "p4 info":
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
This assumes a Listbox called ResultBox.
Another example shows how to access the contents of a particular file:
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)
This will print the results of the file into the temporary file in either TextFileName or BinaryFileName from which it can be further processed.
A very simple VB form project is to be found here: p4vbTestForm.txt - change the file extension to .frm and import into a new VB project and try executing a few commands.
There are currently the following other functions implemented in the DLL:
[
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);
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.
[
entry("p4ServerVersion"),
helpstring("returns version of the p4d server last talked to"),
]
Long p4ServerVersion();
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).
The meaning of the magic numbers is information you will have to ask Perforce about!
[
entry("p4GetPort"),
helpstring("returns value of P4PORT"),
]
BSTR p4GetPort();
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.
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.
[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);
First create an object, and then call the Start method, specifying 0 for the default changelist, or alternatively the number.
You can then get and set the various properties such as a list of Files, list of Jobs, or the Description.
Finally do the submit with the Finish method, and check the results by calling InfoArray and ErrorArray.
As an example:
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