Visual LISP: Applications

When I was first learning the AutoLISP® programming language, I came across a quote in which someone called LISP a big pile of mud and who added for good measure that writing functions had the net result of creating an even bigger pile of mud. In this bleak view, sooner or later that pile of mud—your much-labored over application—conceals whatever you were hoping to get out of it in the first place and runs slower and slower. Try sharing that with other users.

But the Visual LISP™ integrated development environment (VLIDE) has changed all of that. In a previous article we explored the concept of Visual LISP projects and how programmers use them to organize libraries of functions, compile code for faster operations, and build a single file from a collection of source files. Now we are going to look at applications that push those concepts a bit further, always keeping in mind that application creation is the ultimate destination of a project.

An application is a third type of VLIDE file known as a VLX (Visual LISP executable). Just like LSP and FAS files, a VLX can load and run a Visual LISP program. The difference as far as AutoCAD® software is concerned is that a VLX is a stand-alone program, which means it's completely self-contained. Everything you need to use the application is in the VLX—not divided amongst multiple files. And the variables, functions, and other source files in VLX are NOT exposed but protected behind a security shield. To expose these elements, you must use specific functions for that purpose.

Exposure

The issue of exposure is far more important than speed. If an application behaves well and does what it is supposed to do, then speed is not normally an issue unless program execution requires several minutes or even hours. And you can sometimes fix that by redesigning the program. In those circumstances, a speed factor increase of 2:1 is significant. Even so, most Visual LISP programs are considered interactive, meaning that a "long" processing time is a matter of seconds.

Exposure is critical, particularly when the application is in the field and has many users. In this situation, exposure equates with errors and far more technical support issues.

Of course there are levels of exposure. But when you're exposing the source code of a somewhat complex application, problems and potential problems increase. Dialog source files go missing or variables get changed, which then cause the program to malfunction. Using FAS files in your project protects variables. But VLX applications provide even more protection and are totally self-contained.

For example, a VLX file can also contain DCL and Visual BASIC project (DVB) files. When a dialog box is part of an application, it travels with the VLX file. The DCL file becomes part of the source files and is not separately distributed with the application. That means end-users can put the VLX file anywhere they please and you don't have to worry about how the your program is going to locate the dialog box source modules. It also means that the end-users cannot change the dialog boxes since they are now part of the compiled VLX file. Thus, the VLX file provides coverage for the exposure that dialog boxes typically present.

Exposed functions and variables are also problematic. A function is automatically exposed when it is defined with the command prefix (C:). But what about the other functions and variables that are all symbols in the eyes of Visual LISP? To understand this aspect of Visual LISP and the runtime environment we need to explore the concept of NameSpace in the system.

What Is NameSpace?

NameSpace is the Visual LISP solution to the problem of managing symbols across multiple documents (see Figure 1). With the NameSpace tool, you can program symbol exposure. You can determine exactly when (or if) symbols are exposed. The easy way to conceptualize NameSpace is to think of each application as having its own place or box to store symbols. That way the same symbol name can exist multiple times in the system. But in each box it can take on a different value.

Suppose we have a symbol that houses a selection set of entity names. Obviously that selection is useless in another drawing since the entity names are not relevant to that drawing. But what if there is more than one Visual LISP program loaded and each one uses the same symbol name? This happens frequently when common names such as "SS1" or "TMP" are used as symbols. Even though the proper programming procedure is to use these common names only as local symbols to a function, they are sometimes used globally in relationship to a set of functions.

The NameSpace concept short-circuits this problem. From the AutoCAD operator level, each open document or drawing is seen as having its own NameSpace. The NameSpace for a document is called the document space. A VLX program loaded in a drawing can then claim its own unique NameSpace within that document space.

NameSpace prevents Visual LISP from confusing symbol references. An application running in a NameSpace uses the symbols in that NameSpace only. Another program running in document space cannot access the symbols inside a NameSpace application.

Thus the document space can contain a symbol of the same name as one in a program space. And the two will not interfere with each other. Add another program space (by loading another VLX) and you can conceivably have yet another instance of the same name but in yet another protected area.

How do you transfer data in and out of a program space area? Visual LISP provides several functions just for that purpose. Depending on where something is destined, different functions come into play. Let's look at the options.

Moving Symbols to and from the Current Document Space

You may want to move data between an application's NameSpace and the document space so that a program can retrieve data from variables set by the operator or set in a different program. Or so that the program can write retrieved data back to the document space to be shared by other processes. Use the VL-DOC-REF subr to retrieve data from document space into a program's local NameSpace. Use VL-DOC-SET to send data from the local NameSpace to the document space.

VL-DOC-SET is like a SETQ expression for a symbol except that the symbol is found in the document space and not in the program space. Using it is virtually error-free IF you're in document space. Under those circumstances the function is the same as a SETQ since it is merely assigning a value to a symbol in the document space.

VL-DOC-SET and VL-DOC-REF both utilize quoted symbols as arguments. The quoted symbol is the symbol name that is to be used in the document space. This symbol does not have to correspond with a symbol of the same value in the current NameSpace. That can get confusing if you are not careful about sending data back and forth or about what you are doing with the names.

Functions are also symbols, but they require a different mechanism for transfer in and out of a program's space. Use the subrs VL-DOC-IMPORT and VL-DOC-EXPORT for transferring functions. VL-DOC-IMPORT brings functions defined in other VLX modules into the current NameSpace. To import a function, you must first export it from the other VLX module. Use VL-DOC-EXPORT to export functions. With these subrs you can create programs whose functions you can export other applications or programs that can import functions of interest from other applications.

To find out what functions another VLX module has made available, use the subr VL-LIST-EXPORT-FUNCTIONS, which produces a list of the function symbol names declared as exported for a loaded VLX. The name of the VLX is provided as a string. Of course, if you wrote the applications being used, you already know the function names. You can use this subr to check versions or available features of other VLX modules (by defining a version-specific function and seeing if it is in the list).

Using a coordinated VL-DOC-SET and VL-DOC-REF setup between two program modules is one way to send and receive data from other NameSpace environments in the current document. To send data to other document spaces, use the VL-PROPAGATE subr. The symbol will be set in all current documents and any other documents loaded in the same session. VL-PROPAGATE is useful for locking up database access by other programs during updates, informing other applications that certain modules are already available (normally ARX modules), and broadcasting messages to other related applications in other documents.

A more surgical approach for sending data between named VLX spaces is called the "blackboard." VL-BB-SET puts and VL-BB-REF gets data in the blackboard memory area. Again, this is a coordinated communication between processes in that the receiving routine assumes the sending routine has placed the data ahead of time. Also note that the REF and SET pair are for data values only and not for functions.

The blackboard is transparent to the operator unless they are using Visual LISP themselves. But symbols placed in the blackboard are available to any application using the VL-BB-REF with a proper symbol name. Thus the exposure is low but not eliminated.

Setting Up a VLX Application

So far we have talked about the methods of exposing programs to other programs, but we have not talked much about the creation of a VLX file. The reason is that the process is incredibly simple if you use the Application Wizard.

As you know, a software wizard walks you through the basic options available to you in preparing something for future use. In this case, the VLX application creation wizard is going to build a "make" file, which defines how the VLX is created. Keep in mind that you can change values for the various options—and thus control the make file—as you move through the wizard.

VLX creation involves LSP source files or compiled FAS files. You can use either although most developers use FAS files because FAS files best approximate the final runtime environment for testing. If you provide LSP files, they will be compiled in any case. So it really does not matter if you provide LSP or FAS files. Just use one or the other so that testing and final release are easier.

To start the wizard:

1. From the File pull-down menu in the VLIDE main window, select Make Application, which opens a fly out menu of various application make options.

2. Select "New Application Wizard…", which starts the wizard for a new application (see Figure 2)

3. Select the Simple or Expert radio button, according to your goals, and click Next.

4. The next screen prompts you to specify the location where the application is to reside, and the process continues in that manner until all the data needed to construct a VLX application has been supplied.

The essential information you need to create a VLX is as follows. (And of course, by the time you're ready to convert a project into an application, you'll know this information inside and out.)

• Application location. Where do you want to store the VLX file?
• Application name. What name is used to reference the application?
• Use separate NameSpace. Option flag to utilize NameSpace.
• Support for ActiveX. Automatically load Active X support library.
• Source files (LSP or FAS). List of files that make up the program.
• Resource files (DCL, DVB, VLX, Text). Optional list of additional files.
• Linkage & Optimization. Compile and link option.

You can always go back and edit these parameters and rebuild the the application later using the other options under the Make Application menu. That means you can experiment with the settings to see what works best for your application. Not all applications are well suited to working in a NameSpace type of environment. For example, an application that is a host to other applications (by providing a large library of exposed functions) is not a good candidate for NameSpace. This is because using NameSpace would require the inclusion of a long list of symbols that have to be imported or exported each time the functions are run. It may be simpler to provide complete exposure in that circumstance.

Summary

Anyone who writes applications has to deal with the issue of how much of the source code symbology to expose to end-users. Exposure can be bad: end-users can manipulate those symbols outside of the application and cause application failure. Exposure can be good: Applications that are highly exposed are certainly seen in some quarters as promoting highly customizable open systems. You have to decide how much exposure is enough at the design stage of application development. Changing direction later on in the process is not a good idea.

Once you've made the exposure decision—and much further down the line—think about providing the application as a VLX file. VLX applications are self-contained: they can hold all the files needed for the application to execute, including text files, dialog box definitions, and so on. And the end-user can store this self-contained module anywhere because once it is loaded, the entire system is operational.

Using NameSpace for applications development is almost a requirement for third-party developers. Selling your software all around the world requires that you tightly control access to the symbols the application uses. Of course, sharing your application with just one other user can be problematic as well, thus the use of NameSpace is strongly recommended regardless. It is important that any applications you write work and play well with other applications.

For in-house developers and those who write code for others to use, using a VLX file for final distribution has numerous advantages:

• You're providing just a single, self-contained file to share.
• With VLX, symbol exposure is limited and so is technical support time: end-users cannot manipulate the symbols and damage program execution.
• VLX files load and run faster than LSP or FAS files.

Building VLX files is easy, understanding how they work and play with others requires a little thinking. And making your own requires a bit of planning. But that is why they are for applications and not just for simple macros. Of course, if you follow my basic advice, those simple macros will eventually yield an application and then you'll want to create a single self-contained load file. VLX will be your solution.

Keep on programmin'.