Load AutoLISP routines at start up and execute commands or functions at specific times during a drawing session.
AutoCAD-based products load the contents of three user-definable files automatically: acad.lsp, acaddoc.lsp, and the MNL file that accompanies your current customization file.
By default, the acad.lsp file is loaded only once, when the program starts, whereas acaddoc.lsp is loaded with each individual document (or drawing). This lets you associate the loading of the acad.lsp file with application startup, and the acaddoc.lsp file with document (or drawing) startup. The default method for loading these startup files can be modified by changing the setting of the ACADLSPASDOC system variable.
If one of these files defines a function of the special type S::STARTUP, this routine runs immediately after the drawing is fully initialized. As an alternative, the APPLOAD command provides a Startup Suite option that loads the specified applications without the need to edit any files.
The acad.lsp and acaddoc.lsp startup files are not provided with AutoCAD-based products. It is up to the user to create and maintain these files.
When you load an AutoLISP file, the command definitions in the file take up memory whether or not you actually use the commands. The AutoLISP autoload function makes a command available without loading the entire routine into memory. Adding the following code to your acaddoc.lsp file automatically loads the commands CMD1, CMD2, and CMD3 from the cmds.lsp file and the NEWCMD command from the newcmd.lsp file.
(autoload "CMDS" '("CMD1" "CMD2" "CMD3"))
(autoload "NEWCMD" '("NEWCMD"))
The first time you enter an automatically loaded command at the Command prompt, AutoLISP loads the entire command definition from the associated file. AutoLISP also provides the autoarxload function for ObjectARX applications.
You can create an acad.lsp file if you regularly use specific AutoLISP routines. When you start AutoCAD, it searches the support file search path for an acad.lsp file. If an acad.lsp file is found, it is loaded into memory.
Because the acad.lsp file is intended to be used for application-specific startup routines, all functions and variables defined in an acad.lsp file are only available in the first drawing. You will probably want to move routines that should be available in all documents from your acad.lsp file into the acaddoc.lsp file.
The recommended functionality of acad.lsp and acaddoc.lsp can be overridden with the ACADLSPASDOC system variable. If the ACADLSPASDOC system variable is set to 0 (the default setting), the acad.lsp file is loaded just once: upon application startup. If set to 1, the acad.lsp file is reloaded when a new drawing is created or an existing drawing file is opened.
The acad.lsp file can contain AutoLISP code for one or more routines, or just a series of load function calls. The latter method is preferable, because modification is easier. If you save the following code as an acad.lsp file, the files mysessionapp1.lsp, databasesynch.lsp, and drawingmanager.lsp are loaded every time you start the program.
(load "mysessionapp1") (load "databasesynch") (load "drawingmanager")
The acaddoc.lsp file is intended to be associated with each document (or drawing) initialization. This file is useful if you want to load a library of AutoLISP routines to be available every time you start a new drawing (or open an existing drawing).
Each time a drawing opens, AutoCAD searches the library path for an acaddoc.lsp file. If it finds one, it loads the file into memory. The acaddoc.lsp file is always loaded with each drawing regardless of the settings of ACADLSPASDOC.
Most users will have a single acaddoc.lsp file for all document-based AutoLISP routines. The program searches for an acaddoc.lsp file in the order defined by the library path; therefore, with this feature, you can have a different acaddoc.lsp file in each drawing directory, which would load specific AutoLISP routines for certain types of drawings or jobs.
The acaddoc.lsp file can contain AutoLISP code for one or more routines, or just a series of load function calls. The latter method is preferable, because modification is easier. If you save the following code as an acaddoc.lsp file, the files mydocumentapp1.lsp, build.lsp, and counter.lsp are loaded every time a new document is opened.
(load "mydocumentapp1") (load "build") (load "counter")
When the program loads a customization (CUI/CUIx) file, it searches for an MNL file with a matching file name. If it finds the file, it loads the file into memory. This function ensures that the AutoLISP functions that are needed for proper operation of user interface elements are loaded.
For example, the customization file acad.cuix looks for the file acad.mnl which might define numerous AutoLISP functions used by user interface elements in the customization file. The MNL file is loaded after the acaddoc.lsp file.
(command "menu" "newmenu") (princ "Newmenu utilities… Loaded.") (Princ)
In this example, calls to the princ function can be used to display status messages. The first use of princ displays the following at the command prompt:
Newmenu utilities… Loaded.
The second call to princ exits the AutoLISP function. Without this second call to princ, the message would be displayed twice. As mentioned previously, you can include the onfailure argument with calls to the load function as an extra precaution.
You can define an S::STARTUP function to perform any needed setup operations after the drawing is initialized.
The startup LISP files (acad.lsp, acaddoc.lsp, and MNL) are all loaded into memory before the drawing is completely initialized. Typically, this does not pose a problem, unless you want to use the command function, which is not guaranteed to work until after a drawing is initialized.
If the user-defined function S::STARTUP is included in an acad.lsp, acaddoc.lsp, or MNL file, it is called when you enter a new drawing or open an existing drawing. Thus, you can include a definition of S::STARTUP in the AutoLISP startup file to perform any setup operations.
For example, if you want to override the standard HATCH command by adding a message and then switching to the BHATCH command, use an acaddoc.lsp file that contains the following:
(defun C:HATCH ( ) (alert "Using the BHATCH command!") (princ "\nEnter OLDHATCH to get to real HATCH command.\n") (command "BHATCH") (princ) ) (defun C:OLDHATCH ( ) (command ".HATCH") (princ) ) (defun-q S::STARTUP ( ) (command "undefine" "hatch") (princ "\nRedefined HATCH to BHATCH!\n") )
Before the drawing is initialized, new definitions for HATCH and OLDHATCH are defined with the defun function. After the drawing is initialized, the S::STARTUP function is called and the standard definition of HATCH is undefined.
Because an S::STARTUP function can be defined in many places (an acad.lsp, acaddoc.lsp, or MNL file or any other AutoLISP file loaded from any of these), it's possible to overwrite a previously defined S::STARTUP function.
The following example shows one method of ensuring that your startup function works with other functions.
(defun-q MYSTARTUP ( )
... your startup function ...
) (setq S::STARTUP (append S::STARTUP MYSTARTUP))
The previous code appends your startup function to that of an existing S::STARTUP function and then redefines the S::STARTUP function to include your startup code. This works properly regardless of the prior existence of an S::STARTUP function.