Wednesday, June 11, 2008

Pro/E VB API: A First Look

A peek under the hood of the new API for Wildfire 4

In case you didn't know about it, PTC introduced a new PFC based API for Pro/Engineer, starting with Wildfire 4. It's called the VB API and it allows code to be written in Visual Basic that can communicate with Pro/Engineer. (For the curious, it does not work with older versions of Pro/Engineer, sorry)

Unlike Pro/WebLink, it is not limited to running in the embedded web browser. Applications written with the VB API can be run almost anywhere that supports a Visual Basic environment (i.e. in an Excel macro). It's important to understand how this new API works in order to understand some of its limitations and to write robust applications.

The API is an asynchronous PFC API, which means that it shares a set of core classes and methods which are mostly identical to Pro/WebLink and J-Link. It is asynchronous in that VB API applications run outside of the Pro/Engineer process (i.e. in Excel, Word, etc), but still can communicate and control the Pro/Engineer session.

EXE COM Server?

Similar to Pro/WebLink, it is implemented as a COM server, but (interestingly) not as a DLL. While a VB API application is running, an executable called "pfclscom.exe" starts and runs in the background. This introduces a major limitation.

Only one VB API program can run at a time, even if there are multiple Pro/Engineer sessions. If a second VB API application tries to start, it won't be able to connect to any Pro/Engineer session if the first one is still connected. As long as the first application has disconnected, the second connection will be successful.

This is a little disappointing, because one can have several asynchronous Pro/Toolkit applications connected to a single Pro/Engineer process at the same time. In fact, there could be any number of Pro/Toolkit applications connecting to any number of Pro/Engineer sessions. There is really no underlying technical restriction causing this limitation.

You had me at goodbye

Those familiar with asynchronous Pro/Toolkit and J-Link applications probably already know that the main steps in an asynchronous application are: 1) Connect to the Pro/Engineer session, 2) Do some stuff, 3) Disconnect. While step 2 is somewhat optional, step 3 is absolutely critical.

The primary reason is that Pro/Engineer keeps track of all asynchronous connections, and considers connections that have not disconnected as "open". Unfortunately, there is a limit to the number of "open" connections, and that limit is surpisingly low.

If you have an asynchronous application that connects over and over with no disconnect, Pro/Engineer will eventually refuse any further connections. It doesn't matter if it's a Pro/Toolkit, J-Link, or VB API application. The limit is around 58-60 connections. That might sound a little high, but if you run VB API programs from an Excel macro over and over again, you might hit that limit pretty quick. If you disconnect properly, there should be no limit to the number of times you can connect to a Pro/Engineer session.

You'd think that with disconnecting being so important for asynchronous applications, it would deserve some special mention in the documentation. Well, you'd be wrong. Sure, the Disconnect() method is mentioned along with the various flavors of the Connect() method, but there is no mention of the importance of disconnecting. You have been warned.

It it weren't broke, they wouldn't have fixed it

All is not perfect in Pro/Engineer VB land however. Don't waste your time with the C000 build of Wildfire 4. The COM server that comes with the install won't allow any connections.

Another more minor issue has to do with "text message" files that nearly all Pro/Engineer API's use. The "text" directory containing these files would normally be defined in a protk.dat file. This is not used for asynchronous applications. Instead, it is specified as part of the connection process. All of the Connect() methods have an argument that is supposed to identify the "text" directory.

For some reason, this argument is ignored by the VB API. As a result, only files in subdirectories of the Pro/Engineer install can be used (Proe/text/usascii if your language is english). It's not a major problem, but definitely an inconvenience if distributing your code to other users and/or companies.

"Happiness equals reality minus expectations" -Tom Magliozzi

Although I question the choice of an EXE based COM server, on the whole, PTC did a great job making the VB API fully functional and very consistent with its sibling API's (Pro/WebLink and J-Link). While I find that Visual Basic has a kludgey syntax and a somewhat broken object model, the API itself gets the job done.


Joe Varghese said...

I have a request.

I am basically a mechanical engineer with some self taught programming skills.. for me, some of the things you say are bouncers (not getting).. It things like COM, API....

It would have been nicer if you could post some Overall Pictures about these.. some basics that we need to know to understand these..


Hans said...

Hello Marc,

Great post, very interesting!

I am currently working with the VB API, building an application to automate some Pro/E tasks. I was able to make the connection with Pro/E and retrieve models etc., the application was all working fine, until now.

At the moment I'm having some problems that I'm not fully understanding, but probably have something to do with the pfclscom server you describe in your post.

I've written a routine that can change the cells of a family table in Pro/E. It does work sometimes, but after a while an error is thrown stating: " The server threw an exception. (Exception from HRESULT: 0x80010105(RPC_E_SERVERFAULT)).

After this error has been thrown, it is not possible to disconnect or reconnect with the server, it keeps throwing the same error. The only thing that helps is restarting (and with that resetting the pfclscom server). I'm not sure if I'm disconnecting and reconnecting properly (is this necessary witin the routine?).

Do you have any hints that might help me to solve this bug in my application?


Marc Mettes said...

I couldn't tell from your comment, but are you disconnecting each time your program is done?


Arno said...

Hi all,

i'm just into VB API for ProE WF4 and starting to get the basics of it, but progress goes slow..

anyone went deeper into this matter?

for instance one thing that is bothering me right now is this: I can get a parameter value and rewrite this value based on the parameter's name. And i can run a sequence to run over every parameter and give it's value. but i can not get a list of all parameter by their names.

for example: ParameterOwner.ListParams() can give a list of all the Values, Units, Types. But NOT their names that go with it...
I can't imagine that this would not be possible but so far nothing has been mentioned in the user guide or internet.



Marc said...

Typically when you have the Parameter object, you can use something like .Name or .GetName() to find the name.

Email me directly if you have more specific questions at


Prema said...

Hello Marc,

How to connect the Excel sheet program to proe ?

JPP said...

Ok, I know this is an old thread, but I have done everything I have read to set things up to be able to run a macro in excel to control Pro/E, and I still cannot get the VBE to include the Pro/E vb api library in the VB references. Any thoughts?

Marc Mettes said...

To make the VB API work, make sure you take care of the basics.

Use the vb_api_register.bat batch file to register the COM server (pfclscom.exe). Add a system environment variable called PRO_COMM_MSG_EXE and set the value to the path to pro_comm_msg.exe in your ProE/Creo install.

You may need to logout or even reboot. After this the VB API objects should be visible in the Excel Object Browser.

Feel free to email me directly to discuss in more detail.