A VBA programmer can open a DGN file using two methods: OpenDesignFile and OpenDesignFileForProgram. This blog attempts to clear up confusion between the two, and which one to use.
Prefer OpenDesignFile to OpenDesignFileForProgram! OpenDesignFile opens a DGN file in the same way that a user would open a DGN file. Everything you expect to be available is available: level libraries, text styles, reference attachments and so on. When you create a new element, for example, it uses the active symbology. You can add your new element to the active DGN model. What's not to like?
That method is used when you want to work with the contents of a DGN file 'behind the scenes'. It's probably best to use it to query a DGN file rather than attempt to modify it. When you OpenDesignFileForProgram it does not expose the same data as OpenDesignFile. For example, level libraries and text styles are not available; no reference attachments are made. Before you can create a new element, you have to attach the right level library; before you conjure a text element, you must ensure that the text style libraries are available. If you want to work with reference attachments, you must first ensure the the reference cache is loaded. You must write extra code to accomplish what MicroStation does normally.
Some developers think that, because OpenDesignFileForProgram ends with Program, it's a better choice. It isn't. OpenDesignFile is always the best choice. OpenDesignFileForProgram opens a file, yes — but is that open file is some way better for programmers to use? No!
Here's what VBA help says about OpenDesignFileForProgram: Opens a DesignFile that the program controls. The user does not have access to the DesignFile except via the program that calls OpenDesignFileForProgram. In other words, a user can't see anything that you do using OpenDesignFileForProgram unless you explicitly reveal it to your user. Probably the best use of OpenDesignFileForProgram is to read information from another DGN file.
Some programmers argue for performance: OpenDesignFileForProgram is in some way faster than OpenDesignFile. It's not clear how a programmer justifies that argument. It's true that OpenDesignFile initialises the DGN file in MicroStation, and ensures that level libraries, text styles and other resources are available. It's true that OpenDesignFile opens and attaches all references. All that takes time. But, in most cases, that is exactly what you — the programmer — wants.
Before you assert that lack of performance is a problem, consult your users and measure! Analyse your code: there may be some critical procedures than are performance hogs. Attention paid to critical sections — often Do loops and For statements — can make a discernible improvement to execution times. If performance remains a critical issue, and you think that OpenDesignFileForProgram offers an advantage over OpenDesignFile, then you should expand your programming horizons. Microsoft designed VBA to be a rapid application development (RAD) tool, not a high-performance computing environment.
Once you know that your code's functionality is correct, then think about performance. Who thinks that performance is a problem? If it's only you, then there isn't a problem. Are your users complaining of slow execution speeds? However slow your code is, it's still hundreds of times faster than performing the same task manually. If your code does what it's supposed to do, then there's no need to improve its performance until your users start to ask for higher productivity.
A slow program that gives correct results is better than a fast program that behaves erratically. Use VBA as a prototyping tool. When lack of performance becomes an issue, move to a faster implementation: a DLL built from C++ source code will be substantially faster than anything you can create using VBA. With MicroStation CONNECT you also have C# as an option. While not as fast as a compiled C++ app., C# nonetheless offers much better execution times than VBA.
I wrote this blog article to give you a single commendation: Prefer OpenDesignFile to OpenDesignFileForProgram!
Very helpful, thanks for the clarification.