Media Share 13

home *** CD-ROM | disk | FTP | other *** search

/ Media Share 13 / mediashare_13.zip / mediashare_13 / ZIPPED / GRAFX / ALLY30.ZIP / ALLY.DOC < prev next >

Wrap

Text File | 1994-03-24 | 136KB | 2,822 lines

---------------------------------------- ALLY - A Lisp Analyzer (TM) Version 3.0, Shareware Edition User's Manual ---------------------------------------- Copyright 1990-1994 Steve Waskow ALL RIGHTS RESERVED _______ ____|__ | (R) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER ---------------------------------------- Wasco Technical Software 1211 Grand Junction Drive Katy, TX 77450 USA ---------------------------------------- Tel: 713-392-1359 Fax: 713-392-1073 CompuServe: 72020,2031 (Steve Waskow) Internet: 72020.2031@compuserve.com D I S C L A I M E R A N D L I M I T O F L I A B I L I T Y --------------------------------------------------------------------- STEVE WASKOW AND WASCO TECHNICAL SOFTWARE MAKES NO WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THIS SOFTWARE AND ACCOMPANYING DOCUMENTATION. IN NO EVENT SHALL STEVE WASKOW OR WASCO TECHNICAL SOFTWARE BE LIABLE FOR ANY DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF STEVE WASKOW OR WASCO TECHNICAL SOFTWARE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. C O P Y R I G H T N O T I C E A N D T R A D E M A R K S ---------------------------------------------------------------- This product, including all supporting software programs, files and printed documentation, is copyrighted and all rights are reserved by Steve Waskow, Wasco Technical Software. Unauthorized duplication and/or distribution is a violation of U.S. copyright law and international copyright agreements. Copyright (c) 1990-1994 Steve Waskow All Rights Reserved Wasco Technical Software ALLY (tm) and A Lisp Analyzer (tm) are trademarks of Wasco Technical Software. AutoCAD (R) and AutoLISP (R) are registered trademarks of Autodesk, Inc. Other brand and product names are mentioned herein, which are trademarks and registered trademarks of their respective owners. These mentions are of an editorial nature only, with no intention of endorsement or infringement. C R E D I T S ------------- Special thanks to beta testers past and present; Antonio Fernandes, Howard Johnson, Steve Johnson, Larry Leuallen, Eric Michalowsky, David Pitzer and Trent Riley. These gentlemen--as well as other ALLY users too numerous to mention--have provided constructive criticism, numerous suggestions, and helpful support throughout ALLY's development and evolution. To these and other supporters I offer my sincere appreciation. Steve Waskow, 1994 T A B L E O F C O N T E N T S ----------------------------------- 1.0 INTRODUCTION 2.0 QUICK START INSTRUCTIONS 3.0 INSTALLATION AND CONFIGURATION 3.1 SYSTEM REQUIREMENTS 3.2 INSTALLATION 3.3 USING EXTENDED or EXPANDED MEMORY 3.4 INSTALLING ALLY TO RUN IN WINDOWS 3.5 FIRST TIME USERS 4.0 RUNNING ALLY 4.1 RUNNING ALLY FROM DOS 4.2 RUNNING ALLY FROM AUTOCAD 4.3 RUNNING ALLY FROM WINDOWS 4.4 ALLY DATA ENTRY SCREENS AND EDITING KEYS 4.5 MOUSE SUPPORT 5.0 ALLY SETUP OPTIONS 5.1 INSTALL USER PROGRAMS 5.2 DEFINE PAGE 5.3 CATEGORIES 5.4 REPORT OPTIONS 5.5 EXECUTION OPTIONS 5.6 VIDEO OPTIONS 5.7 PRINTER OPTIONS 5.8 ABOUT ALLY 6.0 THE ALLY WORKBENCH 6.1 FILE/DESTINATION 6.2 FILE SELECTION 6.3 WORKBENCH COMMANDS 7.0 THE ALLY CHECKER 7.1 COLOR CODING 7.2 PARENTHESES ERRORS 7.3 LINE POINTER 7.4 MOUSE SUPPORT 7.5 LINE EDITING 7.6 CALLING THE USER'S EDITOR 7.7 OTHER BROWSING KEYS 8.0 THE ALLY ANALYZER 8.1 ERROR FUNCTIONS 8.2 FOREACH CONTROL VARIABLES 8.3 DCL FUNCTIONS 8.4 DECLARATIONS AND SYMBOL SCOPE 8.5 ANALYZING MULTIPLE FILES 8.6 EXTERNAL SYMBOLS AND FUNCTIONS 8.7 EXAMPLE AUTOLISP PROGRAM 8.8 STATISTICS AND WARNINGS 8.9 FILE HIERARCHY OF USER DEFINED FUNCTIONS 8.10 FUNCTION CALL HIERARCHY - DYNAMIC SCOPE 8.11 CROSS-REFERENCE OF USER DEFINED FUNCTIONS 8.12 CROSS-REFERENCE OF USER DEFINED SYMBOLS 8.13 CROSS-REFERENCE OF RESERVED LISP SUBRS AND SYMBOLS 8.14 PROGRAM LISTING 8.15 ANALYZER SCREEN OUTPUT 9.0 PROBLEMS AND ERROR MESSAGES APPENDIX A - ASCII TABLE APPENDIX B - PRINTER COMMANDS APPENDIX C - STRING-EMBEDDED CODE 1.0 I N T R O D U C T I O N ============================= ALLY is a programmer's workbench, code checker and analyzer for AutoLISP, to assist you in writing, debugging and documenting AutoLISP code. The workbench integrates ALLY, your favorite DOS text editor and other programs to create a personalized programming environment, accessible from either DOS or AutoCAD. The Analyzer generates a function call hierarchy and a comprehensive cross-reference of variables and functions with each symbol fully identified, scoped and categorized. The analysis provides extensive error checking, and is useful in identifying symbol scopes, interactions and dependencies. The Checker is a custom AutoLISP code browser which uses color coding to provide a fast and convenient visual check of mismatched parentheses, misplaced or missing string quotes, and missing comment semicolons. 2.0 Q U I C K S T A R T I N S T R U C T I O N S ======================================================= If you are the type of individual who likes to jump right in, the following instructions will get you off to a quick start. We do recommend, however, that you review the manual before attempting to use ALLY extensively. QUICK INSTALLATION 1. Insert the ALLY program diskette into drive A (or B). 2. Enter "A:" (or "B:") to make it the default drive. 3. Type "INSTALL" and press [Enter]. 4. Follow the on-screen instructions. QUICK START o To use ALLY from the AutoCAD command line, type "ALLY" and press [Enter], just like any other AutoCAD command. o To use ALLY from the DOS command prompt, change to the ALLY directory, type "ALLY" and press [Enter]. 3.0 I N S T A L L A T I O N A N D C O N F I G U R A T I O N =================================================================== 3.1 SYSTEM REQUIREMENTS ------------------------ ALLY's system requirements are basically the same as AutoCAD's. The minimum system supported is a 286 IBM compatible with 640K RAM, math chip, hard drive, and MS-DOS 3.1 or higher. ALLY currently supports AutoCAD R10 286 DOS, R10 386 DOS, R11 286 DOS, R11 386 DOS, R11 Windows, R12 386 DOS and R12 Windows. ALLY runs as a "Windows Aware" DOS application in Windows 3.1, 386 Enhanced Mode. 3.2 INSTALLATION ----------------- ALLY's installation/configuration program is named INSTALL.EXE. Log onto the drive and directory which contains ALLY and enter "INSTALL" at the DOS prompt. The program first prompts you to choose Installation or Configuration. For new installations or upgrades, enter "I" for Installation. The installation process begins with a search of your hard drives to locate existing AutoCAD support files. No files are modified during this initial search. The information gathered allows INSTALL to automate installation for single, multiple and even mixed AutoCAD versions. Once the search is complete, you will be asked to name a directory for ALLY. It is best to place ALLY in its own directory, so in most cases, this should simply be "C:\ALLY". It is not necessary to install ALLY on your AutoCAD path. After copying ALLY's files into the named directory, INSTALL's next step is to make minor modifications to your ACAD.PGP and ACAD.LSP files. You will be prompted before any modifications are actually made. The first file modified is ACAD.PGP, into which INSTALL adds a single command line. The following is an example of the command INSTALL adds. Note that the 280000 byte shell size shown in the example is a default only used for 286 versions of AutoCAD. Shell sizes are ignored by 386 and Windows versions of AutoCAD, so you will find it set to zero in such installations. ALLY3,C:\ALLY\ALLYWB,280000,,4 Next modified is ACAD.LSP. If you do not have an ACAD.LSP file, one will be created. INSTALL adds just a single line of code to the bottom of the file. The following is an example of the line INSTALL adds. (if (= (load "C:\\ALLY\\ALLY" "f") "f") (princ " *<ALLY load failed>* ")) ALLY cannot be installed directly into a protected ACAD.LSP file, so the installation program creates a "wrapper" if one is encountered. This is a relatively simple process with no ill effects. First, the protected ACAD.LSP file is renamed to ACADn.LSP, where n equals 1 (as in ACAD1.LSP) or the next higher number which will yield a unique file name. INSTALL then creates a new ACAD.LSP file containing load commands for both the renamed original ACAD.LSP and ALLY.LSP. INSTALL's final step is to create or update the ALLY.BAT and ALLY.LSP files in the ALLY directory. To change the few defaults set by the installation program, you can re-run it in Configuration mode at any later time. The installed ALLY must now be setup prior to use. ALLY's setup handles the detailed configuration, in which you select execution and output options, and provide information on other programs you wish to incorporate into the Workbench. See the following section, ALLY SETUP OPTIONS, for instructions. 3.3 USING EXTENDED or EXPANDED MEMORY -------------------------------------- ALLY can be configured to use XMS (extended memory) or EMS (expanded memory) for its swapping operations. Refer to the section ALLY SETUP OPTIONS, Execution Options, for details of the "Swap ALLY to" option. In running ALLY from DOS versions of AutoCAD, keep in mind that without intervention AutoCAD may default to using all extended and expanded memory. This will not prevent ALLY from operating, but will limit ALLY to disk swap files. To instruct AutoCAD to reserve EMS or XMS for ALLY's use, you must change certain AutoCAD settings. XMS and EMS memory usage in 286 versions of AutoCAD can be controlled with AutoCAD's acadxmem and acadlimem environmental variables, respectively. XMS and EMS usage in AutoCAD 386 can be configured via the -demandload, -maxvcpimem, -maxxmsmem and -maxextmem switches of AutoCAD's CFIG386.EXE program. The demandload switch (R11 and later, R11 requires the updated v2.6 DOS Extender from AutoCAD's NEWDX utility) is the most practical and easiest to use of the four switches mentioned. Demandload normally leaves enough extended memory for ALLY's use, without removing it from the pool available to AutoCAD. Refer to AutoCAD's Installation and Performance Guide for more details of memory management specific to your hardware and software. 3.4 INSTALLING ALLY TO RUN IN WINDOWS -------------------------------------- Although a DOS application, ALLY is "Windows aware" and will run under Windows 3.1 in 386 Enhanced mode. The standard installation and setup procedure is enough to run ALLY from AutoCAD R11 for Windows. Additional steps are required to run ALLY independently under Windows and with AutoCAD R12 Windows. To set up ALLY to run as a stand-alone application from the Windows Desktop Manager, perform the following steps. 1. From Window's Program Manager, open the group window you want ALLY to appear in (we suggest using the AutoCAD group). 2. Choose NEW from Program Manager's FILE menu to open the NEW PROGRAM OBJECT dialog. 3. Choose PROGRAM ITEM, then choose OK to open the PROGRAM ITEM PROPERTIES dialog box. 4. Type C:\ALLY\ALLYWB.PIF in the COMMAND LINE field (use appropriate path). 5. Choose CHANGE ICON. If the "no icons available" alert box appears, choose OK to ignore it and open the CHANGE ICON dialog. 6. Type C:\ALLY\ALLYWB.ICO in the FILE NAME field of the CHANGE ICON dialog (use appropriate path). 7. Choose OK to return to the PROGRAM ITEM PROPERTIES dialog box, which will now display the ALLY icon. 8. Choose OK, and the ALLY icon will appear in the program group. Windows uses Program Information Files (PIF) to store settings which affect the way it executes individual DOS programs. The PIF file used for ALLY depends on the AutoCAD release it is run from. AutoCAD R11 for Windows uses the settings from ALLYWB.PIF, an approach which works well. AutoCAD R12 Windows uses a simpler, if less flexible approach. It uses the settings from Window's general purpose _DEFAULT.PIF to run ALLY and other shell applications. Since the standard _DEFAULT.PIF settings are inadequate for ALLY, AutoCAD R12 Windows users must do one of two things. The first option is to launch ALLY independently from the Program Manager rather than calling it from within AutoCAD. The only disadvantage to this arrangement is that you loose ALLY's interactive file loading feature. The second option is to replace your existing _DEFAULT.PIF file with the modified version shipped with ALLY. First, save a backup of the original _DEFAULT.PIF in your Window's directory by renaming or moving the file, then copy the _DEFAULT.PIF from the ALLY directory to the Windows directory. This will give ALLY adequate performance when executed from AutoCAD R12. Be aware that other applications using _DEFAULT.PIF will consume more Windows resources with the new file than they did previously. Here are some general tips for using ALLY with AutoCAD for Windows. Always exit ALLY by its own exit commands. When you execute ALLY from within AutoCAD, do not try to minimize ALLY to complete some drawing task. Though visible, AutoCAD is in a suspended state. Should you make this mistake, regain control by pressing [Alt-Esc] to cycle back through the open tasks to ALLY. AutoCAD will be reactivated when you exit ALLY. 3.5 FIRST TIME USERS --------------------- Although no trouble is anticipated, in keeping with the spirit of "better safe than sorry", we suggest you save your drawing and any open files prior to executing ALLY the first few times you try it. This is especially wise if you have a highly customized system or are trying an untested video mode in ALLY. If other DOS programs work for you through AutoCAD's SHELL, you should expect no trouble with ALLY, once properly installed. Once it is apparent that no problems exist, the act of saving the drawing first is unnecessary. 4.0 R U N N I N G A L L Y ============================== 4.1 RUNNING ALLY FROM DOS -------------------------- To use ALLY from the DOS command prompt, change to the ALLY directory, and enter "ALLY". If desired, ALLY's path can be prefixed or the ALLY directory added to the DOS PATH statement to execute ALLY from any directory. ALLY also allows a filename to be specified as a command line parameter. The current path and a LSP extension is assumed if not included as part of the filename. If a filename is not passed as a parameter, ALLY defaults to the file last worked on. The complete syntax follows: [drive:][path]ALLY [[drive:][path]filename[.ext]] 4.2 RUNNING ALLY FROM AUTOCAD ------------------------------ Properly installed, ALLY's AutoCAD interface is automatically loaded via your ACAD.LSP file. To use it, enter "ALLY" at the AutoCAD command prompt. The system switches to text mode and the ALLY Workbench appears--with the AutoLISP file last checked or analyzed as the default file. Upon exiting ALLY, you are returned to AutoCAD where you will be asked if you want to load the file or files last examined in ALLY. 4.3 RUNNING ALLY FROM WINDOWS ------------------------------ Inside of AutoCAD for Windows, just enter "ALLY" as described above. To run ALLY independently of AutoCAD, double-click the ALLY icon from Window's Desktop Manager. See the installation chapter INSTALLING ALLY TO RUN IN WINDOWS for additional information on the Windows environment. 4.4 ALLY DATA ENTRY SCREENS AND EDITING KEYS --------------------------------------------- The ALLY Workbench and Setup programs have a series of data entry fields for user input. Use the cursor keys or mouse to move about the screen to add or change entries. The active field is always highlighted. Fields can also be selected with a mouse by picking the field with the mouse cursor. To exit any menu or data entry screen, press [F10], [Alt-X], or use a mouse to pick the [F10]-Exit function from the top command menu or the exit window button in the upper left hand corner of the window. This section is a summary listing of common command keys. Following chapters will detail additional keys used in other components of ALLY. The following keys are common to all components of ALLY which perform editing or data entry. [Enter] . . . . Enter key, enters data or picks item from a selection list. [Up], [Down], [Right], [Left] Cursor keys, moves the cursor left/right/up/down. [^Left] . . . . Control-Left cursor moves the cursor left one word. [^Right] . . . . Control-Right cursor moves the cursor right one word. [Home] . . . . . Moves cursor to the start of the line or the top of the list. [End] . . . . . Moves cursor to the end of the line or bottom of the list. [PgUp] . . . . . Moves to the top of the window or display previous page. [PgDn] . . . . . Moves to the bottom of the window or display next page. [Ins] . . . . . The Insert key toggles the insert/overwrite mode. [Esc] . . . . . Undo changes to the current line, exit menu, or abort pending command or active process. [BkSp] . . . . . Deletes the character to the immediate left of the cursor. [Del] . . . . . Deletes the character directly above the cursor. [^End] . . . . . Deletes text from the cursor position to the end of the line. [^Home] . . . . Deletes text from cursor position to the start of the line. [Spacebar] . . . Toggles the entry of a highlighted fixed response field, such as YES/NO and NAME/EXTN/TIME/SIZE. [MouseRight] . . The Right mouse button performs the same function as the [Spacebar] for fixed response fields. [MouseBoth] . . Clicking both right and left mouse buttons simultaneously is the same as pressing [Esc]. [MouseLeft] . . The left mouse button serves as a Pick/Enter key. 4.5 MOUSE SUPPORT ------------------ The following is a brief listing of areas in which ALLY supports mouse input. More details are available in the documentation of the influenced commands. o Commands. Pick any command listed at the top or bottom of the screen to execute the command. o Responses to Prompts. Respond to prompts which require a fixed reply, such as YES/NO and NAME/EXTN/TIME/SIZE, by picking the response to the right of the message prompt. o Menu Choices. Choose any listed item in a menu window by picking it with the mouse. o Data Entry Windows. Pick any field on a data entry window to move the cursor and highlight bar into it. o Checker Line Pointer. Pick any position on the Checker's screen to reposition the line pointer. o Window Exit Buttons. Pick the rectangle in the top left hand corner of a window border to exit the window. o Filename Selection. Picking a name in the file selection window which is not highlighted moves the highlight bar to the picked position. Picking the highlighted file name selects the file and exits the window. o Scroll bar Slider. Pick any position on the file selection scroll bar to reposition the slider. Hold button down to drag the slider to desired position on the scroll bar. o Scroll bar Arrows. Pick up or down arrows to scroll one item at a time, hold button down to scroll continuously. o Checker Scroll Arrows. Pick the up or down arrows on the Checker's command line to scroll the line pointer up or down, hold button down to scroll continuously. 5.0 A L L Y S E T U P O P T I O N S =========================================== ALLY setup options can either be set directly from DOS or from the ALLY Workbench. From DOS type "ALLYSU" and press [Enter]. From the ALLY Workbench you can press either [F2] or [Alt-O], or use your mouse to pick [F2]-Opt in the top command menu line. The Options screen presents a main menu of options. o------- Options --------+ | Install User Programs | | Define Page | | Categories | | Report Options | | Execution Options | | Video Options | | Printer Options | | About ALLY | +------------------------+ To make a menu choice, you can either cursor to the desired option and press [Enter], press the highlighted first letter of option name, or pick the option with your mouse. Each menu choice will bring up a new screen, most of which are data entry windows. We next describe each screen in detail. 5.1 INSTALL USER PROGRAMS -------------------------- This is where you install your external programs into the ALLY Workbench. There are fields for your browser, text editor, and up to 8 other external programs or DOS commands. The browser attaches to key [F7]/[Alt-B], the editor to key [F8]/[Alt-E], and other user programs are attached to keys [Ctrl-F1] through [Ctrl-F8]. o-------------- Install User Programs --------------+ | F7 Browser: ~list ] | | F8 Editor : ~c:\qedit\q.exe ] ^ | |^F1 Program: c:\sdk\lb ] [.new | |^F2 Program: @c:\sdk\kelv ] > d:\x\;.k | |^F3 Program: c:\sdk\protect d:\x\;.k g c:\app\;.lsp| |^F4 Program: c:\util\ljbook * | |^F5 Program: ~fc /l /c /w /n ] [.bak | list /s | |^F6 Program: del *.bak | |^F7 Program: copy ] ? | |^F8 Program: print * | +---------------------------------------------------+ With properly installed user programs, editing, browsing and other operations are a one key operation in ALLY. The user installed editor must be capable of editing and saving files in a plain ASCII format. The browser can be any one of many common utilities for viewing ASCII files or, if you desire, your editor can be used for browsing. Both the editor and browser must be capable of loading a file by specifying it as a command line parameter, but this is an almost universal feature. For best results with the ALLY Checker, the text editor should also provide for a command line parameter which will direct it to position the cursor at a specific line of the file. Consult your editor's documentation, most good editors have this capability. To maximize the memory available for running user programs, ALLY swaps itself nearly completely out of conventional memory. AutoCAD itself does not do as well, so if you plan to run ALLY from within AutoCAD, you are generally better off using small memory efficient programs rather than large, full-blown applications. Some word processors, for instance, may require more memory than can be made available with AutoCAD in the background. External programs and DOS commands are installed in the same fashion, except internal DOS commands (such as COPY) have no path or file extension. Just enter the command or program name followed by any required command line parameters. If a program's directory is not listed in DOS's path, prefix the program name with its full directory path. If you give the full path name of your program and the file extension (for example: C:\QEDIT\Q.EXE), ALLY will execute it directly, without first loading a new copy of the DOS command interpreter (command.com). Depending on the version of DOS being used, this will make as much as 3.5 kilobytes more memory available to the program being executed. Other special instructions, filenames and command parameters require one or more of the following ALLY special symbols in the user program command line. Right bracket - Pathname alias ------------------------------ ALLY's various file and path name aliases allow it to automatically provide current file information to user programs and commands. A right bracket (]) is used as a full pathname alias. When you add a right bracket as a command line parameter, ALLY converts it to the full path and filename of the selected LISP file. The example below shows the user command as you would enter it, and the command as ALLY expands it assuming that the currently selected file is C:\DEV\LAY.LSP. list ] = list C:\DEV\LAY.LSP Left bracket - Pathname less extension alias -------------------------------------------- The left bracket ([) alias converts to the full pathname of the current file, less the filename extension. This is useful for programs which process an incoming file to a new output file--you can create output files with the same name as the original but a different extension. The example below shows a user command with both right and left brackets, to supply the program with input and output file names. Also shown is the result of ALLY's expansion of the command, assuming the currently selected file is C:\DEV\LAY.LSP. c:\sdk\lb ] [.new = c:\sdk\lb C:\DEV\LAY.LSP C:\DEV\LAY.new Semicolon - Filename less path and extension alias -------------------------------------------------- The semicolon (;) alias converts to the current filename less path and extension. Similar to the left bracket alias, it is useful for specifying output files with the same file name as the original, but with a different path and extension. The example below is a modification of the one used previously, this time using semicolon to allow output to a different directory. c:\sdk\lb [ c:\clean\;.new = c:\sdk\lb C:\DEV\LAY.LSP c:\clean\LAY.new Asterisk - Report pathname alias -------------------------------- A lone asterisk symbol (*) converts to the full path and filename of the Analyzer report file. This is useful for sending ALLY's report file to a printing or formatting utility. The asterisk symbol must be separated from the rest of the command line by spaces to prevent ALLY from confusing it with the DOS wildcard character. The asterisk symbol in the example below provides the current report file name to a printing utility. ALLY's expansion of the command is also shown, assuming a report file of C:\TMP\LAY.RPT. c:\util\ljbook * = c:\util\ljbook C:\TMP\LAY.RPT Question mark - Pause for input command --------------------------------------- If you place a lone question mark (?) in the command line, ALLY pauses at execution time to allow you to add parameters or edit the command line. The question mark must be separated from the rest of the command line by spaces to prevent ALLY from confusing it with the DOS wildcard character. The command line editor positions the cursor at the position of the question mark. For example, assuming the current file is C:\DEV\LAY.LSP, the following COPY command pauses for the user to enter a destination. copy ] ? = copy C:\DEV\LAY.LSP _ Ampersand - Switch to directory prefix -------------------------------------- If a program must execute from within its own directory, include its path and prefix it with an ampersand symbol (@). The ampersand forces a directory change to the program's directory before execution, and a directory change back after execution. This is useful for programs which expect their support files to be in the current directory. In the example below, ALLY will make D:\SDK the active directory before executing the program, and will return to the previous directory after the program executes. @c:\sdk\kelv ] > d:\x\;.k = c:\sdk\kelv C:\DEV\LAY.LSP > d:\x\LAY.k Tilde - Keep video mode prefix ------------------------------ The tilde prefix allows the same video mode control for user programs that Execution Options' "Keep mode in DOS" does for the DOS shell. When a tilde symbol (~), is placed in front of the user command, ALLY retains its video mode when executing the program or command. Retaining ALLY's video mode is useful for editors, browsers and other programs which can operate in extended modes. The example below shows the tilde prefix for the browser. If, for instance, ALLY is operating in 132 column x 43 row text mode, the browser will appear in the same screen resolution when called by ALLY. ~list ] If you do not add the tilde prefix, ALLY restores the previously active DOS video mode before executing the program or command. The ALLY video mode is restored when you exit back to ALLY, regardless of changes outside. The tilde prefix can be used in conjunction with the ampersand prefix, the order of appearance is not important. Carat - line number alias ------------------------- A line number alias is used to support executing your editor from the ALLY Checker. Many text editors allow a special parameter which directs them to jump to a specific line of the file specified for editing. Using the carat symbol (^) to represent the line number, enter the rest of the "go to" command line parameter per your editor's instructions. The line number is meaningful only when the Editor is called from the ALLY Checker. When the [F8]-Edit command is executed from the Checker, the user's editor is called upon to load the file and position the cursor on the same line the Checker is viewing. This is different than the general [F8]-Edit command in ALLY's Workbench, which simply passes line number 1 to the editor. Below, specific examples are given for use of the carat alias with Qedit and Brief editors, other editors will likely expect a different format. Also shown are the commands as ALLY expands them, assuming C:\DEV\LAY.LSP is in the Checker positioned at line number 91. ~c:\qedit\q.exe ] ^ = c:\qedit\q.exe C:\DEV\LAY.LSP 91 c:\brief\b.exe ] -m"goto_line ^" = c:\brief\b.exe C:\DEV\LAY.LSP -m"goto_line 91" Combined symbols ---------------- There is no limit as to how you can combine ALLY's special symbols. Here are some more examples of ALLY's command expansions. c:\sdk\protect d:\x\;.k g c:\app\;.lsp = c:\sdk\protect d:\x\LAY.k g c:\app\LAY.lsp ~fc /c /w /n ] [.bak | list /s = fc /c /w /n C:\DEV\LAY.LSP C:\DEV\LAY.bak | list /s If ever in doubt as to how ALLY is expanding a user command line, add a question mark pause command at the end of the line. You will then get an opportunity to inspect the expanded command. TSR programs ------------ TSR programs should not be installed as ALLY user programs unless they are already loaded and resident prior to executing ALLY (and prior to AutoCAD, if ALLY is used from AutoCAD). To be of any use when attached to an ALLY user program key, the TSR program must be accessible from the DOS command line after going resident, in lieu of or in addition to intercepting a hot key. One suitable TSR program is DOS's PRINT program. Assuming PRINT is resident prior to running ALLY, the following user command can print report files in the background. print * = print C:\TMP\LAY.RPT If you use the above PRINT command, be careful to not overwrite or otherwise disturb the file while printing. 5.2 DEFINE PAGE ---------------- These options affect the page format and page size of Analyzer reports. o------ Define Page ------+ | Page width······: 80 | | Left margin·····: 2 | | Right margin····: 2 | | Page length·····: 66 | | Top margin······: 2 | | Bottom margin···: 2 | +-------------------------+ Page width ---------- Enter the page width for ALLY's report. The report page width is adjustable from 70 to 255 characters, defaulting to 80 characters wide. For a typical narrow carriage dot-matrix printer, try using 80 for its normal (10 CPI) print mode, or 132 for a compressed (17 CPI) print mode. Higher values can be used for laser and wide carriage printers, the maximum width depends on the paper width and font size being used. Left margin ----------- Enter the size of the left margin for ALLY's report. The margin is adjustable from 0 to 10 characters, defaulting to 0 characters wide. Right margin ------------ Enter the size of the right margin for ALLY's report. The margin is adjustable from 0 to 10 characters, defaulting to 0 characters wide. Page length ----------- The page length for the ALLY's report can be set from 44 to 32767 lines, or 0 for continuous paper feed. The length must match your paper and printer settings. Typical defaults are 66 lines for dot-matrix and 60 lines for laser and ink jet printers. Some fonts require different settings. The number of printed lines per page is the page length minus the top and bottom margins. Top margin ---------- Enter the length of the top margin for ALLY's report. The margin is adjustable from 0 to 10 lines, defaulting to 2 lines. Bottom margin ------------- Enter the length of the bottom margin for ALLY's report. The margin is adjustable from 0 to 10 lines, defaulting to 2 lines. 5.3 CATEGORIES --------------- In this window choose the categories you wish the ALLY Analyzer to report. Turn individual report categories on or off with a YES or NO response. o------ Categories -------+ | Statistics······: YES | | File hierarchy··: YES | | Call hierarchy··: YES | | X-ref functions·: YES | | X-ref symbols···: YES | | X-ref reserved··: NO | | Program listing·: YES | +-------------------------+ Statistics ---------- The statistical section summarizes code and comments processed, functions and symbols found, and includes several other measures of processed code. File hierarchy -------------- ALLY's file hierarchy is a tree structure of all user defined functions, which optionally shows each functions beginning and ending line numbers. Call hierarchy -------------- The call hierarchy is a tree structure of all called and user defined functions, illustrating their dynamic scope and dependencies. X-ref functions --------------- This is ALLY's cross-reference of all user defined functions, showing where each is declared, defined, and used. Optionally, you can include summaries showing the functions and symbols declared and used by the function. X-ref symbols ------------- All user defined symbols which are not functions are cross-referenced in this section. Declarations and each instance of use are shown. X-ref reserved -------------- This cross-reference of AutoLISP's reserved symbols includes the predefined constants, such as Pi, T and nil, and AutoLISP's built-in subrs (functions). Although useful in identifying AutoLISP version compatibility, memory requirements and execution time of the Analyzer increase with its use. Program listing --------------- This option adds a listing of the analyzed AutoLISP source files to the report. Each line is numbered to cross-reference with the listing of functions and symbols. This is valuable for locating reported errors and instances of symbol use, and should always be used for producing final program documentation. 5.4 REPORT OPTIONS ------------------- These options effect the output of the report the ALLY Analyzer produces. o---- Report Options -----+ | File tree detail: YES | | Call tree level·: 0 | | Function summary: YES | | Detach globals··: YES | | Detach undefined: YES | | Double space····: NO | | ASCII lines·····: YES | | Form feeds······: YES | | Printer commands: NO | | Page breaks·····: LIST | +-------------------------+ File tree detail ---------------- By default, ALLY's file hierarchy tree displays the beginning and ending line numbers of all user-defined functions, and includes lambda functions. If you answer NO, the file tree will show function names without details such as line numbers, and will not include lambda functions. Call tree level --------------- This leveling option allows you to specify the maximum depth for branches of the function call hierarchy tree. Leveling gives you an abbreviated view of the hierarchy tree if you are only interested in major functions a few levels deep. See the FUNCTION CALL HIERARCHY section of the manual for an illustration of leveling. Each function call is a branch of the tree. A branches level is its depth from the global root. When the call tree level is set to zero, the default, ALLY creates the entire hierarchy tree without leveling. When the call tree level is set between 2 and 30, branches of the tree deeper than the specified level from the global root are pared off, with an indicator. Function summary ---------------- Answer NO to this option, and the ALLY Analyzer will omit the default "declares" and "uses" summaries from function cross-references, and only display instances of the functions. Detach globals -------------- The detach globals option splits ALLY's function and symbol reports into global and local sections. This can be a convenience when scrutinizing the report to identify global symbols which can be declared local. Detach undefined ---------------- This option allows you to separate the cross-references of undefined and external functions into a separate category. This can be used with or without the above described "Detach globals" option. Double space ------------ Answer YES to force the listing of the source file to be printed double spaced, with room to add editorial comments. ASCII lines ----------- If you respond YES, the ALLY Analyzer will use the "box" characters from the IBM extended character set to draw lines and tree diagrams in its report. If your printer or editor does not support this character set (perhaps producing foreign or italic characters instead), turn this option off with NO. When off, ALLY substitutes dashes and other common characters which any printer should be capable of producing. Form feeds ---------- If YES, ALLY inserts hard form feed characters (ASCII 12) to terminate each page. If NO, blank lines are used to pad the bottom of each page to the specified length. Printer commands ---------------- By default, ALLY does not include hard form-feeds and user-defined printer setup and reset strings in Analyzer reports written to files (FILE and EDITOR destinations). If you plan to create report files for printing at a later time with the DOS PRINT or COPY commands without reformatting, respond YES to this option to ensure the files include the printer codes ALLY normally uses for outputing reports to the printer. Page breaks ----------- Enter YES, NO or LIST. The ALLY Analyzer generates several distinct sections in its reports. YES forces a page break after each of the sections--regardless of length. NO uses the least amount of paper to generate a printed report, by allowing report sections to follow directly behind one another as page space permits. LIST, the default, allows the analysis sections of the report to mix but forces a page break between program listings, so that they may be separated and studied side-by-side with the analysis. 5.5 EXECUTION OPTIONS ---------------------- These options effect the way the ALLY programs operate. o--- Execution Options ---+ | Tab expansion···: 8 | | Read buffer size: 1 | | File sort method: NAME | | Default to last·: YES | | Browse 2 files··: NO | | Edit 2 files····: NO | | Pause Analyzer··: NO | | Use mouse·······: YES | | Swap ALLY to····: DISK | +-------------------------+ Tab expansion ------------- Enter the number of spaces that Tabs (ASCII 9) in your source code should be expanded to in Analyzer reports and Checker displays. It is adjustable from 2 to 8 spaces, default is 8. Read buffer size ---------------- Enter a size for ALLY's line reading buffer, 1K to 64K. The buffer size dictates the maximum line length that the Analyzer and Checker can read. A 1K buffer allows 1024 character lines and is generally adequate. Increasing the buffer decreases the memory available for analyzing and checking. File sort method ---------------- Enter a default sorting method for the ALLY Workbench point-and-shoot file selection window. Choose NAME, EXTN, TIME or SIZE. The default sorting order can be changed when selecting files. Default to last --------------- By default, ALLY's file selection starts in the directory of the file which was last analyzed. If NO, file selection will always start in the current directory. Reload ALLY after editing this option for the change to take effect. Browse 2 files -------------- When reports are destined to BROWSER, a YES causes ALLY to send both the report and source file names to the browser's execution command line. This option is useful for "windowing" browsers which can switch between or display two files on the screen simultaneously. Edit 2 files ------------ When reports are destined to EDITOR, a YES causes ALLY to send both the report and source file names to the editor's execution command line. This option is useful for "Windowing" editors which can display and edit two files simultaneously. Pause Analyzer -------------- When the pause option is on, ALLY pauses after completing the analysis so that you can review the status window before browsing the report. Press [Esc] to abort or any other key to continue. Use mouse --------- This option controls whether or not ALLY makes use of a mouse. ALLY automatically determines whether or not a mouse driver is present, but this option provides a means to totally disable the mouse event handler in case of conflict. Reload ALLY after editing this option for the change to take effect. Swap ALLY to ------------ The swap option allows users to choose a destination for ALLY's swap; EMS, XMS or DISK. The default is DISK, which creates a temporary swap file (about 96K in size) in the ALLY directory. Swap files are named in the format ALLYnnnn.$$$, and are deleted during ALLY's normal exit routine. The EMS option works with any expanded memory manager providing EMS 3.x or higher. The XMS option operates with extended memory managers such as HIMEM.SYS, QEMM, 386^MAX, and NETROOM. VCPI support provided by EMM386 and most modern memory managers allow the XMS option to work even if the manager is configured to simulate EMS memory. ALLY requires about 96K of EMS or XMS. If the selected type of memory is absent or insufficient when ALLY is run, it uses a disk swap file instead. See the USING EXTENDED OR EXPANDED MEMORY section for details on configuring AutoCAD to share memory with ALLY. 5.6 VIDEO OPTIONS ------------------ These options effect ALLY's video display resolution and use of color. o----- Video Options -----+ | Force video mode: NONE | | User video mode·: 69 | | Keep mode in DOS: NO | | Allow from ACAD·: NO | | Resistor colors·: NO | | Mono colors·····: NO | +-------------------------+ Force video mode ---------------- The force video mode option has three choices: NONE, VGA, and USER. NONE tells ALLY to execute in the current DOS video mode, without switching modes itself. With this setting, ALLY will operate properly in any character resolution, even extended text modes set by another utility. Choose VGA to force ALLY to switch to 80x50 text mode if VGA, or 80x43 text mode if EGA. These 50/43 line VGA/EGA modes are standard, independent of video card manufacture. Choose USER to force ALLY, at startup, to switch to the video mode defined in the "User video mode" field, described below, generally used to define high-resolution extended text modes. User video mode --------------- Enter any extended video text mode in this field, using hexadecimal notation. If the previously described "Force video mode" field is set to USER, ALLY will attempt to switch into the user-selected video mode at start-up. Since extended mode numbers are specific to brand, refer to your video card manual for a listing of applicable text mode numbers. If a manual is unavailable, refer to the text file VGAMODES.DOC supplied with ALLY. This document lists 132 column text modes for several common adapters. If you are unsure of the brand, Microsoft's MSD.EXE program (included with MS-DOS 6.x and Windows 3.1) is capable of identifying many video adapters. The user video mode option is designed primarily for EGA and VGA cards which use standard BIOS calls to set video modes, but ALLY does detect and support some non-standard models. VESA standard SuperVGA extended text modes are supported as well. Most modern VGA cards are VESA capable, although some require a companion TSR program to be loaded. Numbers 02..FF hexadecimal are used for the OEM (Original Equipment Manufacturer) extended modes, and numbers 100..FFF hexadecimal are reserved for VESA extended modes. Forty column text modes 0 and 1, and graphics modes (if detectable) are either ignored or rejected. Keep mode in DOS ---------------- NO causes ALLY to restore the previous DOS active video mode before shelling to DOS from the Workbench, and to restore ALLY's video mode upon return. YES causes ALLY to retain its current video mode, row and column resolution when shelling to DOS. Be aware that present MS-DOS ANSI.SYS drivers do not support extended text modes, and will not write to the extended portions of the screen. If you have ANSI installed and wish to try DOS in extended text modes, remove ANSI.SYS from your CONFIG.SYS file or switch to an ANSI replacement with extended mode support, such as ANSI.COM by PC Magazine. Allow from ACAD --------------- YES allows ALLY to function from AutoCAD just as it would from DOS. Choose NO to force ALLY to override all other video configurations when it detects it is being run from AutoCAD, and prevent video mode changes. The NO option is only necessary when ALLY is used with certain display-list processor and video card combinations which do not tolerate video mode changes from AutoCAD's shell. A bad video combination usually results in a corrupted graphics screen display upon returning to AutoCAD. Resistor colors --------------- This allows you to choose the color set used for coloring parentheses in the ALLY Checker. The default color set attempts to maximize contrast in nested parentheses. The alternate resistor color set follows the Brown-Red-Orange-Yellow-Green-Blue-Violet-Gray-White-Black sequence which certain users with electronics background may find more familiar and informative. Answer YES to force ALLY to use the Resistor color set. This option is only valid for color displays. Mono colors ----------- Although ALLY generally provides automatic video detection, you can set this option to force it to use monochrome (black and white) colors for its screen displays, regardless of the actual hardware. Forcing monochrome mode also defeats all other ALLY video mode configurations. 5.7 PRINTER OPTIONS -------------------- Use the printer options screen to select a printer port and set up printer defaults for Analyzer reports. Scrolling input fields allow the Printer Setup and Printer Reset strings to contain up to 254 characters. o----------------- Printer Options ------------------+ | Printer port·: LPT1 | | Printer setup: 15,27,48 | | Printer reset: 18,27,50 | +----------------------------------------------------+ Printer port ------------ Use this field to tell ALLY which communications port your printer is attached to--LPT1, LPT2, LPT3, COM1, COM2, COM3 or COM4. The most common connection is LPT1 (often by redirection), try this if you are unsure which port your printer is attached to. Serial printers must be initialized to the proper baud, parity, databits, etc. with the DOS MODE command. Printer setup ------------- This entry is optional, used to define a string of control codes and/or escape sequences to be sent to your printer prior to printing ALLY's reports. Printer commands are hardware specific--although some de facto standards exist, compatibility may be limited to a subset of commands. Most differences in control codes occur between the different technologies--laser, dot-matrix, etc. See your printer manual for codes specific to your hardware. List control characters, escape sequences, or a string of both. Each code and character must be entered in its decimal ASCII value with each value separated by a comma. Blank spaces are not required between codes (ALLY will strip them out anyway) and leading zeros are optional. Appendix B further describes printer commands and contains a condensed table of commands specific to IBM, Epson and compatible dot-matrix printers. Appendix A, an ASCII table, will help you to convert other printer commands to the required format. To illustrate the method, let's set an Epson compatible dot-matrix printer to condensed print mode and 1/8 inch line spacing. The control code to turn on the printer's condensed print mode is SI (Shift In), which is decimal ASCII 15. To set 1/8 inch line spacing, the escape sequence ESC+0 is required. ESC (Escape) is decimal ASCII 27, and the character 0 (zero) is decimal ASCII 48. Thus the string you enter to send these two commands is: 15,27,48 Printer reset ------------- This entry is optional. The instructions for entering a reset string are the same as for entering a printer setup string. This is normally used only in conjunction with a printer setup string, to return the printer to its previous state. To continue the example we began with the setup string, let's return the printer to its previous state. The control code to turn the condensed print mode off is DC2 (Device Control 2), which is decimal ASCII 18. To reset the line spacing to a normal 1/6, the escape sequence ESC+2 is required. ESC (Escape) is decimal ASCII 27, and the character 2 (two) is decimal ASCII 50. The developed reset string is: 18,27,50 Sample printer configurations ----------------------------- The following sample configuration summarizes the examples used previously for an Epson compatible narrow carriage dot-matrix printer. It configures the printer to use its built-in 17 cpi condensed print mode and an 88 line page with 1/8 inch line spacing (with continuous form pager, the entire 11" page length is printable, so 1/8" spacing = 11" page length/88 lines). To support this setup, ALLY's "Define Page" window must be set with a page width of 132 and a page length of 88, or 0 for continuous paper feed. Setup: 15, 27, 48 Reset: 18, 27, 50 The next sample setup is for an HP Laserjet compatible printer. It configures the laser printer to use its built-in 16.67 cpi line-printer font with a 5.45/48" line spacing (laser printers are limited to 10" printing area on an 11" long page, so 5.45/48" spacing ≈ 10" printable page length/88). To support this setup, ALLY's "Define Page" window must be set with a page width of 132 and a page length of 88, or 0 for continuous paper feed. Setup: 27, 38, 108, 53, 46, 52, 53, 67, 27, 40, 49, 48, 85, 27, 40, 115, 48, 112, 49, 54, 46, 54, 55, 104, 56, 46, 53, 118, 48, 115, 48, 98, 48, 84 Reset: 27, 69 5.8 ABOUT ALLY --------------- Choose this menu item to display some brief information about ALLY's developer. 6.0 T H E A L L Y W O R K B E N C H =========================================== ALLY starts up in the Workbench at the main File/Destination data entry screen. Here you select the file search mask, the file and report directories, the source file to be analyzed, checked, or edited, and the report destination. Function keys are available for help, for configuring ALLY, and to perform actions such as executing the ALLY Analyzer, a DOS shell, your editor, file browser and other installed external programs. 6.1 FILE/DESTINATION --------------------- This is the main ALLY screen, where you select AutoLISP files and direct their reports. All ALLY functions are available from this screen: editing, checking, analyzing, and other user installed programs. o---------------- File/Destination ------------------+ | File search mask: *.LSP | | File directory··: D:\ACAD12\SUPPORT\ | | Report directory: E:\ | | Lisp file name··: D:\ACAD12\SUPPORT\DLINE.LSP | | Destination·····: SCREEN | | Report file name: E:\DLINE.RPT | +----------------------------------------------------+ File search mask ---------------- This is the search mask that the ALLY pop-up file selection window ([F3] or [Alt-F]) uses to select which files are displayed. The default is *.LSP, but you may enter any combination of wildcard and match characters that DOS permits. Do not prefix a path to the search mask. File directory -------------- This is the directory path where your AutoLISP source files are located. The path must contain the appropriate drive letter and must be terminated with a backslash. If you do not supply a path, ALLY inserts the current path. The pop-up file selection window ([F3] or [Alt-F]) searches from this field's directory, and updates it when directories are changed. By default, ALLY starts up with the file directory being used the last time it was run. The "Default to last" option of EXECUTION OPTIONS can change this behavior to startup with the current directory. Report directory ---------------- ALLY uses the report directory, by default, as a destination for report file output. Like the file directory, this must be a valid path with a drive letter and terminating backslash--if blank, the current path is inserted as a default. This directory is also used for temporary files created for reports sent to the browser. If you have a ram disk with adequate free space, naming it as the report directory may result in a significant speed increase. You can override this default path for EDITOR and FILE destinations by editing the report file name after an AutoLISP file has been selected. Lisp file name -------------- Enter the name of the AutoLISP file you wish to operate on. Your chosen file directory automatically prefixes the file name, but you can enter a different path name if needed. If you omit the file extension, ALLY adds .LSP by default. When changing a file name, the old name clears if any key other than a cursor or editing key is pressed first. Rather than manually entering the LISP file name, you can select files from ALLY's point-and-shoot file selection window (press function key [F3] or [Alt-F]). Destination ----------- Use this field to direct the ALLY Analyzer's report to your choice of SCREEN, FILE, PRINTER, BROWSER or EDITOR. The SCREEN option directs the output to a simple screen display routine, which pages but does not provide backward scrolling. The FILE option writes the report to the named output disk file. PRINTER prints the report to the printer attached to the specified port. For BROWSER, ALLY writes the report to a temporary disk file, then loads it into your browser (the temporary file is erased as you leave the browser). When EDITOR is chosen for the destination, ALLY writes the report to the named output disk file and loads it into your editor. Report file name ---------------- Enter the file name for the report generated by the ALLY Analyzer. A file name is only required when FILE or EDITOR has been chosen for the destination. ALLY will automatically fill this field, using the chosen report directory and the same file name as the AutoLISP source, except with a RPT extension. You can edit this field or enter a different path or name if desired. If you change the name but omit the file extension, ALLY adds .RPT by default. 6.2 FILE SELECTION ------------------- Point-and-shoot file selection is available from the ALLY Workbench by pressing [F3] or [Alt-F]. A window pops up with a file listing gathered from your specified file directory and filename search mask. Drive letters and subdirectories are also included, and are marked and displayed in unique colors. Lists which contain more items than can fit in the window will scroll as you traverse them. The files are sorted according to the default order chosen in ALLY's Setup Options. To temporarily change the sort method, press [F9] or [Alt-S] and choose NAME, EXTN, TIME or SIZE. Pick your selection by moving the highlight bar over the file or subdirectory name and pressing [Enter]. The [Up] and [Down] cursor keys traverse the list one name at a time. If you have a mouse, you can move the mouse cursor over the chosen file name and click the left button to highlight the file. Clicking the left mouse button again with the mouse cursor over the highlighted file enters your selection. There are other ways to move the highlight bar through longer lists. Typing the first character of a file name moves the highlight bar to the first matching file. Typing the second character within two seconds of the first moves the highlight bar again to the first name matching both characters. ALLY continues to track and match the name so long as you continue to type characters within two second intervals. The string of characters being tracked are displayed below the file selection window. After a two second interval, the tracking string clears. You can force the tracking string to clear at any time by pressing the spacebar. The [PgUp] and [PgDn] keys page the highlight bar up or down the length of the window, and [Home] and [End] move it to the respective ends of the list. The right hand side of the file window is a mouse sensitive scroll bar. The slider on the scroll bar shows the position of the highlighted file relative to the length of the file list. The up and down arrows at the top and bottom of the scroll bar are mouse hot spots. Pick the arrows with the mouse to cursor up and down, holding the mouse button down will scroll continuously. Pick any position on the scroll bar to reposition the slider and file list. To make a high speed cruise through the file list, hold the mouse button down on the slider and drag the slider up or down the scroll bar. Press [Esc] to exit the file selection window. You can also exit by pressing [F10] or [Alt-X], pressing both mouse buttons simultaneously, or by picking the exit window button in the upper left corner of the window border with the mouse. To take a quick peek at a file, highlight it and press [F3], [Alt-P] or the right mouse button. The first three lines of the file will be displayed at the bottom of the screen. Other ALLY commands--Check, Analyze, Browse, Edit, and your [^F1] through [^F8] programs--are active and can be executed on any file highlighted in the list. The directory tree can be traversed by picking a subdirectory name from the list--the window will be redrawn to display files from the new directory. To traverse the directory tree towards the root, pick the displayed directory's parent directory. The parent directory is indicated in the list as a pair of periods followed by a backslash: (..\) To change drives, simply pick the desired drive letter from the list. Alternatively, you can exit the file selection window by pressing [Esc], enter the new drive and directory into the file directory field and press [F3] again. Once a file name is picked, the window clears and the name is entered into the LISP file name field. If FILE or EDITOR is used as the report destination, a matching name with the extension RPT is assigned as the report file. The file directory field is updated each time you pick a file. 6.3 WORKBENCH COMMANDS ----------------------- The ALLY Workbench uses the keyboard's function keys and Alt key combinations to execute commands and perform various actions on the selected AutoLISP source code file. If you are using a mouse, you can move its cursor over any active command item in the menu at the top of the screen, and press the left button to execute the command or program. The top command menu includes the built-in ALLY functions and the user-installed browser and editor. F1-Help F2-Opt F3-File F4-Check F5-Analyze F7-Browse F8-Edit F9-Shell F10-Exit Other user-installed programs and their associated keys are displayed directly below the top command menu. The following is an example of a user program command menu. ^F1 Lb ^F2 Kelv ^F3 Protect ^F4 Ljbook ^F5 Fc ^F6 Del ^F7 Copy ^F8 Print The carat (^) prefix to the user program function keys indicates that they are control keys--for instance, ^F1 means Ctrl-F1. The items in the user program menu can also be picked and executed with a mouse. Help - [F1] or [Alt-H] ---------------------- Pressing [F1] or [Alt-H] displays a help screen. The screen shows a summary of each function key and a brief description of the editing keys available for ALLY's data entry screen. Opt(ions) - [F2] or [Alt-O] --------------------------- These keys bring up the ALLY Setup Options menu. This menu and its sub-menus are described in detail in an earlier section of the manual--see ALLY SETUP OPTIONS. File - [F3] or [Alt-F] ---------------------- Press [F3] or [Alt-F] to bring up ALLY's point-and-shoot file selection window. Its operation is described in a previous manual section titled FILE SELECTION. Check - [F4] or [Alt-C] ----------------------- These keys execute the ALLY Checker. The Checker is a LISP file browser which colorizes parentheses, quoted strings and comments to help you spot errors. The Checker is described in more detail later. Analyze - [F5] or [Alt-A] ------------------------- Pressing [F5] or [Alt-A] analyzes the selected AutoLISP source file with the ALLY Analyzer. Multiple source files can be analyzed together--see the section ANALYZING MULTIPLE FILES. The functions of the ALLY Analyzer itself are described in a later section of the manual. Your current report settings are passed to the Analyzer at execution. As your source file is being analyzed, a running tally of the number of lines, symbols, and errors encountered are displayed on screen. ALLY then writes or prints the report to the selected destination. If the selected destination is your browser or editor, the report file name is passed to the command line and the editor or browser is executed. When the output is to an existing file, you have the option of overwriting or appending the file. You can abort the analysis at any time by picking the exit window button with a mouse or pressing [Esc]. If there are any problems accessing the chosen file--such as a nonexistent file name or directory--ALLY displays an error message and moves the cursor to the offending entry. Because the encryption methods employed produce incomprehensible results, protected AutoLISP files are not allowed to be analyzed. Browse - [F7] or [Alt-B] ------------------------ Press function key [F7] or [Alt-B] to use your installed file browser to browse the selected AutoLISP file. If you have installed the browser using a file name alias symbol (see the [F2]/[Alt-O] Options command), ALLY passes the file name to the browser along with any command line parameters you have entered. When you exit the browser you are returned to the ALLY Workbench. Edit - [F8] or [Alt-E] ---------------------- Function key [F8] or [Alt-E] executes your installed text editor to edit the selected AutoLISP file. If you have installed the editor using a file name alias symbol (see the [F2]/[Alt-O] Options command), ALLY passes the file name to the editor along with any command line parameters you have entered. You are returned to ALLY after exiting the editor. Shell - [F9] or [Alt-S] ----------------------- ALLY implements a sophisticated DOS shell feature, available by pressing function key [F9] or [Alt-S]. ALLY prompts for a DOS command line when the command is entered. ALLY's shell command can be used in two different methods. The first method is a DOS shell. When ALLY prompts you for a DOS command, press [Enter]. Without a command string, ALLY loads a copy of your DOS command interpreter (command.com) and shells out to the DOS environment where you are greeted with the familiar DOS prompt. You can stay in DOS as long as you wish, performing DOS commands or running other programs. To return to the ALLY Workbench, type EXIT at the DOS prompt and press [Enter]. The second method is a program shell. Enter a program name or DOS command at the prompt and press [Enter], and ALLY will execute it, pause, then return to the Workbench after you press a key. You can add command line parameters behind the command and use any of ALLY's special command line symbol except the question mark pause symbol. To execute a program residing in a directory not listed in your DOS PATH statement, you can prefix the program name with its full directory path (example: C:\UTIL\MYPROG). If the program needs to execute from within its own directory, prefix the program path with an ampersand (example: @C:\UTIL\MYPROG). When ALLY encounters the ampersand, it changes to the listed program directory before execution, and back after. If you give the full path name of a COM or EXE executable program and the file extension (example: C:\UTIL\MYPROG.EXE), ALLY will execute it directly, without loading a copy of the DOS command interpreter. With some versions of DOS, this makes as much as 3.5 KB more memory available for the program being executed. You can use any of ALLY's special command prefixes and filename alias symbols when entering your command line. See the preceding INSTALL USER PROGRAMS section for a description of these special symbols. To maximize the amount of memory for the DOS shell, ALLY swaps most of its own code and data out of memory--into extended memory, expanded memory or a temporary disk file. See ALLY SETUP OPTIONS, Execution Options, for details of the "Swap ALLY to" option. There is one warning we wish to stress. You may access a TSR program which is already resident, but never load a TSR while in a DOS shell. Doing so can cause unpredictable results when you try to return to the parent program, and open files could be lost. Exit - [F10] or [Alt-X] ----------------------- Press [F10] or [Alt-X] when you are ready to leave ALLY and return to the operating system (or to return to AutoCAD if you have run ALLY from AutoCAD). You will be prompted to confirm your command to leave ALLY. If run from AutoCAD, you are asked if you want to load the AutoLISP source file which was last examined in ALLY. If you respond yes, the file is loaded into AutoLISP. If multiple LISP files were analyzed with ALLY's special include file directive, they are all loaded--see the section ANALYZING MULTIPLE FILES. Use this feature to load new or modified AutoLISP programs to try them out. If you find more editing is needed, execute ALLY again to automatically return to the same file. User Programs - [Ctrl-F1] through [Ctrl-F8] ------------------------------------------- These keys execute the installed external programs. For more information, see the description of the INSTALL USER PROGRAMS section of the ALLY SETUP OPTIONS chapter. These programs may be executed from either the Workbench or the file selection window. 7.0 T H E A L L Y C H E C K E R ======================================= The ALLY Checker is a LISP file browser which colors parentheses, quoted strings and comments to help you spot errors. Each line of code is numbered on the left side of the screen. Lines longer than the display are wrapped and indented. A plus mark in the line number column indicates a wrapped line. Embedded Tabs (ASCII 9) are expanded to the number of spaces specified in ALLY's Setup Options (the default is 8 spaces). Other control characters (ASCII 0 to 31) are represented by a carat symbol followed by the control letter. For example, a backspace character (ASCII 8) is displayed as ^H. 7.1 COLOR CODING ----------------- Matching left and right parentheses are paired in the same color. Colors change at each level of parentheses nesting, repeating at the tenth level. The line numbers on the left side of the display are colored to match the current open parentheses, or colored cyan if no parentheses are open. You can choose between two different parentheses color sets in ALLY's Setup Options. Normal LISP code is colored light gray, quoted text strings are colored green and comments are colored cyan (regular comments and inline comments--introduced in R12--are supported). This makes quoted strings and comments stand out from the rest of the code. The change (or lack of change) in color makes it easy to recognize cases of missing quote marks and semicolons. 7.2 PARENTHESES ERRORS ----------------------- The right hand side of the Checker's status/command line shows the number of parentheses which are open after the current line. If no parentheses are open, the parentheses indicator is blank. For a quick file-wide check of parentheses errors just jump to the end of the file with the [End] key. If an error involving too many closing parentheses is detected, all following parentheses are displayed in blinking white. This may not necessarily pinpoint the error itself, but does show where the error first becomes apparent. 7.3 LINE POINTER ----------------- The Checker has a movable line pointer which allows you to edit or inspect any line of source code on the screen. The line number's background is highlighted to indicate the pointer position. The pointer can be moved up and down with the cursor keys, and will scroll the file being viewed when it reaches the top or bottom of the screen. 7.4 MOUSE SUPPORT ------------------ Commands can be executed and prompts can be answered by picking responses off the command line with a mouse. The line pointer can be repositioned by using the mouse to pick the new position on screen. The command line's up and down arrows can be picked with the mouse to scroll the file being viewed, and will scroll continuously as long as the mouse button is held down. 7.5 LINE EDITING ----------------- The Checker has built-in line editing capability. Although you can call the user-installed editor from the Checker if you need to do extensive editing, the built-in line editor is perfect for making minor changes--such as correcting a parentheses or quote imbalance. To edit a line of code, position the line pointer at the desired location and press [Alt-L] or [L] for LineEd. The text is loaded in the line editor on the Checker's command line. The line editor can handle individual lines of up to 64K in size, depending on the "Read buffer size" in ALLY's Execution Options. LineEd's editing keys [Ins], [Del] and [BkSp] perform the usual editing functions. [Ctrl-BkSp] is used to delete words. Cursor positioning keys include [Right], [Left], [Home] and [End], with [Ctrl-Right] and [Ctrl-Left] combinations for moving the cursor from word to word. A mouse can also be used to reposition the cursor. To save the changes and exit the line editor, press [Enter]. To abandon changes, press [Esc]. If changes have been made, you will be prompted to save the file when you leave the Checker for the Workbench or the user editor. When saving modifications, the Checker makes a backup with the file extension BAK. 7.6 CALLING THE USER'S EDITOR ------------------------------ ALLY has the ability to execute your editor directly from the Checker with the [F8], [Alt-E] or [E] keys. In addition, if your editor supports it, the file will be loaded with the cursor placed on the line currently pointed to by the Checker's line pointer. See the INSTALL USER PROGRAMS section regarding line number alias. When you finish editing the file, it is automatically reloaded into the Checker and returned to the previous position. 7.7 OTHER BROWSING KEYS ------------------------ [F],[Alt-F] . The Find function is used to enter a text string and initiate a search. Searches start from the top of the file, and are conducted in a case-insensitive manner. If the search is successful, the line pointer is repositioned to the first line which contains the match. If no match is found, the line pointer remains stationary. [N],[Alt-N] . The Next function is used to find additional matches following a successful Find operation. [G],[Alt-G] . The Go-to function prompts for and moves the line indicator to a specified line. [X],[Alt-X] . The Exit function leaves the Checker and returns to the ALLY Workbench. [F10] . . . . Same as [Alt-X], Exit. [Esc] . . . . In the line editor, [Esc] aborts editing and returns to the Checker. When browsing, [Esc] exits the Checker and returns to the Workbench. [Up]/[Down] . Cursor keys, moves line indicator up or down one line. [Home] . . . Moves the line indicator to the first line of the file. [End] . . . . Moves the line indicator to the end of the file. [PgUp] . . . Displays the previous screen of code. [PgDn] . . . Displays the next screen of code. [MouseRight] The left mouse button is the same as pressing the [Down] cursor, but without continuous scrolling. [MouseBoth] . Both mouse buttons pressed simultaneously together is the same as pressing [Esc]. [MouseLeft] . The pick button. The right mouse button is used to pick new positions for the line pointer, and to pick commands and answer prompts on the Checker's command line. 8.0 T H E A L L Y A N A L Y Z E R ========================================= A symbol cross-referencer and more, the ALLY Analyzer performs several functions to help debug and document AutoLISP programs. The Analyzer generates a comprehensive report of statistics, warnings, symbol usage, scope and function calls. Individual report categories are described in the following chapters, and report format options are detailed in ALLY SETUP OPTIONS. The size of files which ALLY can analyze is limited only by available memory- -up to 16 MB of extended memory can be addressed, and each line of the file can contain up to 64K characters. The report destination is user-selectable; choose output to screen, disk file, printer, user-designated text editor, or user-designated file browser. ALLY displays a status window during its analysis. To abort the analysis at any time, press the [Esc] key or both mouse buttons simultaneously. 8.1 ERROR FUNCTIONS -------------------- To insure proper scoping of dynamic symbols to error functions, ALLY treats any binding of a symbol to *error* as a function call, regardless of it being defined or called elsewhere in the code. This includes symbols used to temporarily hold and reset the true *error* definition. 8.2 FOREACH CONTROL VARIABLES ------------------------------ ALLY recognizes the uniqueness of foreach control variables. These control variables are always local in scope to the foreach function, and neither affect, nor are affected by, symbols sharing the same variable name outside the foreach statement. The abbreviation fcv is used in report notations. 8.3 DCL FUNCTIONS ------------------ The Analyzer will read and analyze AutoLISP code embedded in double-quoted action-expression strings of action_tile and new_dialog function calls. The Analyzer cannot, however, evaluate such string-embedded code if it is referenced by variable or further masked in a nested function such as strcat. If action-expression string concatenation cannot be avoided or if the string must be referenced by variable, see Appendix C. This appendix describes a work-around using the special ally_cat alias for strcat which allows ALLY to analyze string-embedded AutoLISP code at any point in your program. 8.4 DECLARATIONS AND SYMBOL SCOPE ---------------------------------- The scope of a symbol is the region of the program's environment where it is accessible for evaluation, established by where--and if--the symbol is declared in a defun (function definition) argument list. A symbol is global if not explicitly declared. Global symbols are stored in the current session's defined symbol list (formerly called the atomlist) and bound (reserved a place in memory to hold values) when first encountered by the AutoLISP interpreter. Global symbols can be set (assigned a value) or evaluated anywhere--by expressions evaluated when the LISP file is loaded, during function execution, or by user input at the command line. Global symbols have global scope. Symbols declared in a defun argument list are local symbols. In addition to arguments, a defun argument list can contain other local symbols as well. Local symbols are both bound and assigned values when the function is entered. Arguments get their values from the function call, other local symbols are initialized to nil. This dynamic binding of local symbols conserves memory, since they are bound only when needed for the function call. Local symbols may be bound to new values as the function executes. Changing the bindings of local symbols does not effect identically named symbols outside the function. When a function exits, all its local symbol bindings are lost and the memory allocated to them recaptured in the next garbage collection. In summary, the scope of a local symbol is the transient localized environment created when the function which spawns it is called. Function definitions can be nested inside other function definitions in the source code. An inner function can be made local to the outer function by declaring its name in the outer function definition's argument list. The benefit of using local functions is the same as using local variables--memory conservation. In AutoLISP a nested function, like any other symbol, is still global if not explicitly declared. Free variables are instances of symbols used inside a function in which they are not local. Free variables are commonly used to produce side effects outside the function. Perhaps the best known class of free variable is the global variable, but it is not the only kind. AutoLISP provides another class of free variable known as dynamic free variables (also referred to as special variables). Dynamic free variables are instances of local symbols used outside the function in which they have been declared. This outside referencing is made possible by AutoLISP's dynamic scoping method. There are two major methods employed for computer language scoping, dynamic and lexical. Dynamic scoping is run-time scoping, whereas lexical scoping is compile-time scoping. AutoLISP's interpreter uses dynamic scoping, which is rare compared to the lexical scoping used by the majority of other, compiled languages. Because AutoLISP's scoping is so unlike other languages with which you may be familiar, it is important to explain the difference. To illustrate the difference between dynamic and lexical scoping, consider the following example. (setq S "three") (defun Test ( / S) (defun Check (S) (Write) ) (defun Write () (print S) ) (setq S "two") (Check "one") (princ) ) Test is a global function. In most languages, functions Check and Write would be considered local to Test, but in AutoLISP they are latent globals--although nested, they are not declared in Test's local symbol list. Their latency is another AutoLISP oddity, due to its interpretive nature. Initially after loading, Check and Write are unavailable outside the function Test, but once Test is called they become global--and would become so even if Test itself calls neither one. The reason for this behavior is that AutoLISP evaluates nothing within a defun statement until the function is called, so AutoLISP initially does not evaluate nested defun statements into operable functions. Our example has been contrived to illustrate the differences between dynamic and lexical scoping, and does not necessarily reflect good programming. Be aware that a global function consumes more memory nested than it does otherwise, because AutoLISP ends up with two copies of the function in its defined symbol list--the nested definition and the actual working copy outside. This doubling also occurs on a temporary basis during execution of a function with nested local functions, but the copies of the locals disappear after use and the memory is reclaimed. If however, a function is aborted due to an error or canceled by the user, any copies of its locals will remain outside--in effect elevating them to global status. Now that we have established the scope of the functions, let us examine the execution of our example. The global symbol S is set to "three" at load time. When executed, Test's local symbol S is set to "two". Test's function call to Check passes the value "one" to Check's argument S, then Check calls the function Write, which prints S. But what value of S does Write print? Under AutoLISP's dynamic scoping, Write will print the word "one", whereas a lexical scoped language would print the word "two". Why? When Write executes, a binding for the symbol S must be found. Both scoping methods require Write's local environment to be searched first, and when a local binding for S is not found, both establish that S is a free variable. The two scoping methods differ in the manner they search for a free variable's binding. A dynamically scoped language such as AutoLISP searches for free variables, top down, in the call stack environments. You can visualize the call stack as a record of active function calls. As each call is made, the called function and its local environment record is placed on the top of the stack, directly above the calling function. A called function may in turn call another, and so on, further deepening the stack. As each function completes its execution and exits, its function record is popped off the top of the stack. The following illustration depicts the call stack growing and shrinking as our example Test function goes through its execution life cycle. +------+ |Write | +------+ |------| +------+ |Check | |Check | |Check | +------+ |------| |------| |------| +------+ |Test | |Test | |Test | |Test | |Test | +------+ |------| |------| |------| |------| |------| +------+ |Global| |Global| |Global| |Global| |Global| |Global| |Global| +------+ +------+ +------+ +------+ +------+ +------+ +------+ Each called function has full access to the local symbol bindings of all other function environments below it in the stack. Where there are multiple local bindings of identically named symbols, the called function uses the first binding encountered in its top down search. The global environment is searched only after exhausting the call stack without finding a match. In our dynamic example, the top down search when Write is at the top of the call stack finds a binding for the dynamic free variable S in the environment of function Check--where "one" is bound to its local argument S. Had a binding for S not been found in Check, the search would have continued down the call stack--to Test in this case, and following that the global environment. Lexical scoping is different. A lexically scoped language searches for free variables, inside out, in nested function environments. For lexical languages, nesting is accomplished by physically placing function definitions inside one another in the source code. Lexical scoping requires no further declaration for a nested function to be considered local to the outer function. Each lexical nested function has full access to the local symbol bindings of all outer function environments. In the case of multiple local bindings of identically named symbols, the nested function will use the first one encountered in its outward search. The global environment is the outermost environment. By default, a function in a lexically scoped language does not have access to the calling environment, unless by chance or design the function is nested within the calling environment. In our lexical example, Write's nearest outer environment is the environment of Test, where "two" is bound to its local symbol S. Had a binding for S not been found in Test, the search would have continued outward to the next level of nesting--which would be the global environment in this example. The following illustrates the differing dynamic stack and lexical environment. +-Write-----------+ +--------Global---------+ | S="one" | | S="three" | | | | | +------Test-------+ | |-Check---|-------| | | S="two" | | | S="one" | | | +--Check--+ | | | | | | | S="one" | | | |-Test------------| | | +---------+ | | | S="two" | | | +--Write--+ | | | | | | | S="two" | | | |-Global----------| | | +-----|---+ | | | S="three" | | | | | | | | | +-----------------+ | +-----------------+ +-----------------------+ DYNAMIC SCOPE CALL STACK LEXICAL SCOPE NESTED ENVIRONMENTS (AUTOLISP) (OTHER LANGUAGES) Now that we have some understanding of how AutoLISP's dynamic scoping differs from the more common lexical scoping, we can examine the reason for using dynamic free variables. All functions will return a value, but consider those which need to effect more than one symbol outside the function. In AutoLISP you can pass arguments to user defined functions by value only. Changing the formal parameters in the function itself does not effect the actual parameters used in the function call. There is no mechanism for passing parameters by reference (variable parameters) such that the actual parameters outside the function can be changed. To work around this limitation, free variables are employed. Global variables can be used, but dynamic free variables are more memory efficient since they are transient local variables at some point in the call stack. Although dynamic free variables can be difficult to track manually, the ALLY Analyzer makes them much easier to manage. Dynamic free variables can be a powerful programming tool when used appropriately, don't be afraid to add them to your arsenal. 8.5 ANALYZING MULTIPLE FILES ----------------------------- By adding special include directives into your source files, ALLY can be used to analyze multiple LISP files and generate a single report of symbol and function interactions. The syntax of the include directive is: ;ALLY([drive:][path]filename[.ext]) Here are a couple of examples: ;ALLY(TrigFunc.lsp) - trigonometric routines. ;ally(D:\Lisp\MyFile) ALLY assumes a filename extension of .LSP if no other extension is given, and will search AutoCAD's support path (set by the ACAD environment variable) for included files if the path is omitted. Use the conventional DOS backslash for directory path separators, not AutoLISP's forward slash or double backslash. The directive statement is not case sensitive, but it is space sensitive. You must not include any blank spaces between the semicolon and the terminating right parenthesis. You may precede the directive with spaces for indentation, but no other characters are allowed to the left of the semicolon. ALLY does not allow two directives in the same line--any text following the directive is ignored, so you may follow the directive with comments. AutoLISP itself ignores ALLY's include directives as comments, so the directives may be placed anywhere in your AutoLISP files. ALLY builds its list of included files as the directives are encountered. The next file in the list is processed after the analysis of the current file is complete. Include directives may be nested to any level, for example, a file included by the main file may contain include directives of its own. Duplicate include directives are ignored, and the order of included files is unimportant except for special cases where functions are redefined from one source file to the next. As an alternative to editing your AutoLISP source files to add include directives, you can create and analyze "project" files--small files which contain nothing but ALLY include directives. You may find that creating and maintaining the include list is easier with this method. When multiple LISP files are analyzed with ALLY's include directives, they are all loaded along with the main file when you use ALLY's automatic AutoLISP load feature. 8.6 EXTERNAL SYMBOLS AND FUNCTIONS ----------------------------------- AutoCAD R11 and later AutoLISP programs can use functions externally defined in ADS programs. This results in AutoLISP files which call functions which, like AutoLISP's internal functions, are never defined in the AutoLISP code. Another common practice is to use separate AutoLISP files to define libraries of standard functions and global symbols. Once thoroughly debugged, you may not want to use ALLY include directives to reanalyze these standard libraries for each new program that relies on them. ALLY considers Autodesk's standard ADS functions and commands defined in ACADAPP.EXP file to be internal AutoLISP functions, but you must inform ALLY of other legitimate external symbols. Otherwise, ALLY reports warnings for any symbol undefined or unset in the analyzed code. It is also desirable to have a mechanism to insure new AutoLISP programs do not inadvertently redefine external functions relied on elsewhere. ALLY uses external symbol files to accomplish this. The format for an ALLY external symbol file follows. Only one symbol may be listed per line. Upper, lower or mixed case is acceptable, and the symbols need not be sorted. Blank lines may be included, and any line beginning with a semicolon is treated as a general comment and is ignored. Individual symbol comments (up to 40 characters) may be added following any symbol, separated by at least one space. These symbol comments are printed in ALLY's reports, allowing you to identify the source of the external symbols. For example: C:SOLMESH std acadr12.lsp function The main external symbol file is named EXTERNAL.SYM, and must reside in the ALLY directory. The default EXTERNAL.SYM shipped with ALLY contains the AutoLISP functions which automatically load when AutoCAD R12 starts in its default configuration. This consists of the functions defined in Autodesk's ACADR12.LSP file, which is loaded with the AutoCAD R12 menu by the ACAD.MNL file. You can modify your installed copy of EXTERNAL.SYM to fit your particular needs. You can also create external symbol files specific to particular AutoLISP applications. These files must share the same file name as the main LSP file being analyzed, except with a SYM file name extension. For example, an AutoLISP file named MYFILE.LSP can have a matching external symbol file named MYFILE.SYM. These application specific external symbol files must be located in the same directory as their mating AutoLISP files, but otherwise follow the same format exemplified in EXTERNAL.SYM. 8.7 EXAMPLE AUTOLISP PROGRAM ----------------------------- The following AutoLISP program is used to illustrate the Analyzer's reports. This itself illustrates the "program listing" option of a typical report. 1 ;; BUB.LSP Copyright (c) 1992, 1994 Steve Waskow 2 ;; Draws item # bubble, leader, and numbers bubble 3 ;; Example program to illustrate Analyzer features 4 5 (defun leader (/ i pt2 drawln) 6 ;draws pline arrowhead and line leader 7 8 (defun drawln () 9 ;draws one or more leader line segments 10 (if (> (distance pt pt2) (* 0.1875 dimsc)) 11 (command ".line" pt pt2 "") 12 (setq pt2 pt pt i i (prompt "\nToo short!")) 13 ) 14 ;ask for another line segment 15 (if (setq i pt pt pt2 16 pt2 (getpoint pt "\nTo point: ") 17 ) 18 (drawln) ;recursively draw next line segment 19 ) 20 ) 21 22 (setq dimsc (getvar "dimscale") ;use for scale 23 pt (getpoint "\nPoint of arrowhead: ") 24 pt2 (getpoint pt "\nLeader to point: ") 25 ) 26 ;draw proportioned arrowhead 27 (command ".pline" pt "W" 0 (* 0.0416 dimsc) 28 (setq 29 pt (polar pt (angle pt pt2) (* 0.125 dimsc)) 30 ) 31 "" 32 ) 33 (drawln) ;draw first line segment 34 ) 35 36 (defun bubble () 37 ;draws bubble centered on last point and item # 38 (command ".circle" pt (* 0.1875 dimsc) 39 ".trim" (entlast) "" pt "" 40 ".text" "M" pt (* 0.125 dimsc) 0 item 41 ) 42 ) 43 44 (defun C:BUB (/ i pt s dimsc) 45 ;auto-incremented item bubble with arrow leader. 46 ;press <enter> at point prompt to place bubble. 47 (setq s (itoa (setq item (if item (1+ item) 1)))) 48 (if (setq i (getint (strcat "\nItem <" s ">: "))) 49 (setq item i) 50 ) 51 (leader) 52 (bubble) 53 (princ) ;exit with no echo 54 ) 8.8 STATISTICS AND WARNINGS ---------------------------- The first section of the Analyzer report includes information and statistics on the analyzed file or files, and warnings of any errors or potential problems encountered. The statistics report--an optional report item--includes several measures of the analyzed code, as shown in the following example from an analysis of BUB.LSP. Characters % Statements % Lines % Code: 613 45 43 75 39 72 Comment: 445 32 14 25 14 26 Blank: 314 23 - - 5 9 Total: 1372 57 54 Maximum Average Line length, number of characters: 51 25.41 Statement depth, per line of code: 5 1.10 Undef/Ext Global Local Total User functions: 0 3 1 4 User variables: - 1 6 7 Internal subrs: - 18 - 18 Avg number times used Avg character length User functions: 1.00 5.75 User variables: 5.86 2.43 Internal subrs: 2.17 - For an accurate representation, CR/LF and ^Z characters are ignored in the character count. Spaces and control characters, such as tabs, are counted as blanks. Code and comment character counts are exclusive of blanks. ALLY supports both regular comments and the new inline style comments introduced in R12. It should be noted that the sum of the code, comment and blank lines may exceed the reported total lines. The reported total is accurate, the seeming inconsistency is due to the fact that lines which contain code and a comment are included in both categories. Warnings and errors, if encountered, follow the statistical data. The warning report is the one report category which cannot be excluded. One common error is mismatch parentheses. ALLY reports parentheses errors beginning with the line the error first became apparent. These errors can be easily located and corrected in the ALLY Checker. The Analyzer also checks that quotations are closed on the same line they are opened, since this is often an unintentional error. Some programmers insert hard carriage returns in quoted text intentionally, and AutoLISP accepts them. ALLY warns you when this condition is found, and lists the line numbers so an inspection of the code can be made. Usually a true quote error will show in several successive line numbers and create one or more parentheses errors in the report. Both parentheses and quote errors are unrecoverable--that is, the analysis of the code beyond the point of error will be inaccurate, since ALLY cannot presume to know where the missing punctuation should go. (HINT: Should this occur, study the report to determine where the analysis has gone awry. This will help you to pinpoint the error). The source code is also checked for improper use of reserved symbol and functions names. For instance, an error is reported if the code sets a value to the reserved symbol T (AutoLISP reserves T for the Boolean TRUE, i.e. non-nil). ALLY checks that reserved symbols and functions are neither set, defined, nor used in a function's argument list. ALLY reports symbols which are declared but never used. Although these extraneous symbols may be harmless, they should be removed to eliminate unnecessary memory overhead. Functions which are called but not defined with defun in the analyzed source code are listed as undefined functions in the warning report. A function listed by ALLY as undefined is not necessarily an error, the function may be defined elsewhere, or set to another function, or created as a list without using defun (a trick we do not recommend). These occurrences, however, are uncommon enough to warrant investigation if you are unsure. If the omission of a function definition is intentional--it being defined elsewhere--you can suppress the warning by including the function name in an ALLY external symbol file (see EXTERNAL SYMBOLS AND FUNCTIONS). Another option, assuming the missing function is defined in a different, supporting AutoLISP file, is to include the other file in the analysis by using an ALLY include directive (see ANALYZING MULTIPLE FILES). Another function warning occurs when two functions share the same name or a function is redefined. This warning is helpful in identifying conflicts between one or more separate AutoLISP programs. Sometimes a redefinition is intentional, other times they are not. Unintentional redefinitions can cause unexpected results or lead to other problems. ALLY also checks for certain scope errors--see the preceding SYMBOL AND FUNCTION SCOPE section for a discussion of scope. A warning is reported when a symbol is referenced in a scope in which it is not an argument or has not otherwise been assigned a value. When multiple files are analyzed, the file name will head each section of the warning report. A sample warning report follows (an invented example, not from BUB.LSP). C:\ACAD\MYFILE.LSP Functions redefined: DoIt 44 Undefined functions: itooa 36 Symbols referenced but unset in scope: i 12,15,16 Reserved symbols reset or redefined: max 49,53,57 t 11,16,17,29 Symbols declared but never used: r2 4 C:\ACAD\TEST.LSP Quote not closed on line 4,5,6,7,8,9,10 Parentheses not closed on line 10 Other types of errors can be found by studying ALLY's report. For instance, it is easy to spot a misspelling of one of AutoLISP's built-in functions, since the misspelled name will immediately show up as an undefined function. 8.9 FILE HIERARCHY OF USER DEFINED FUNCTIONS --------------------------------------------- The file hierarchy which ALLY generates is a tree structure of all user defined functions. This serves as a table of contents of your AutoLISP file. All globally accessible functions are shown as branches of the root file. Nested functions are shown as branches of their parent functions. Lambda functions are numbered sequentially as encountered. The line numbers of the source file for the beginning and ending of each function are shown. When multiple files are analyzed, they are shown as a continuation of the main trunk of the tree diagram. Here is an example of a file hierarchy, taken from an analysis of our sample file BUB.LSP. File C:\ALLY\BUB.LSP |--leader (5-34) | `--drawln (8-20) |--bubble (36-42) `--C:BUB (44-54) Use this report to determine if a function is nested and to quickly locate its position in the file. If you desire less detail you can have ALLY omit the line numbers and lambda references. See the "File tree detail" option in the REPORT OPTIONS section for instructions. 8.10 FUNCTION CALL HIERARCHY - DYNAMIC SCOPE --------------------------------------------- The function call hierarchy generated by ALLY is a tree structure of all called or user defined functions. This tree diagram illustrates the dynamic scope and dependencies of the analyzed functions. The global environment is the root of the tree. Branching off the main trunk are all global functions which are not specifically called by another function. Each function call found produces a function branch off of its calling parent function. If a function is called by more than one parent function, it will be reproduced as a branch for each parent. Functions are arranged alphabetically along common branches. Branches of recursive functions are truncated at the first reoccurrence and marked with three periods following the function name. Indirect recursion--a recursive loop with intervening functions--is illustrated likewise. The following example is taken from an analysis of the sample file BUB.LSP, and illustrates a function, drawln, recursively calling itself. global `--C:BUB |--bubble `--leader `--drawln `--drawln... To determine a function's hierarchy, follow its branch inward to the root. To determine its dependencies, follow its branches outward. For large or complex programs ALLY offers leveling, which allows you to specify the maximum depth for branches of the function call hierarchy tree. The leveling feature gives you an abbreviated view of the hierarchy tree if you are only interested in major functions a few levels deep. See the "Call tree level" option in the REPORT OPTIONS section for details on setting the leveling depth. Branches of the tree which are pared due to leveling are marked with two periods followed by an arrow. The following example (an invented example, not from BUB.LSP) illustrates the results of using call tree leveling. BEFORE AFTER LEVELING TO DEPTH 2 global global `--MainFunct `--MainFunct |--SubFunct1 |--SubFunct1..> | `--SubFunct3 `--SubFunct2..> | `--SubFunct4 `--SubFunct2 `--SubFunct5 TIP: ---- If ALLY's call hierarchy fails to root your program's main function properly due to indirect recursion, you can force a correct hierarchy tree structure by adding a dummy function which calls the main function. For example: (defun DummyRoot () (MainFunct)) Since the dummy function is not called by any other function, it becomes the tree root and the hierarchy which follows it will reflect actual execution: BEFORE, UNDEFINED ROOT AFTER, DUMMY ROOT DEFINED global global `--SubFunct2 `--DummyRoot `--MainFunct `--MainFunct `--SubFunct1 `--SubFunct1 `--SubFunct2... `--SubFunct2 `--MainFunct... 8.11 CROSS-REFERENCE OF USER DEFINED FUNCTIONS ----------------------------------------------- In this section, all user defined functions are listed in alphabetical order. Each function has a separate cross-reference for the parent functions and line numbers in which it is declared, called, defined, referenced, and set. A function's scope is determined by where and if it is declared. The preceding DECLARATIONS AND SYMBOL SCOPE section has a detailed discussion of scope. The function cross-reference can be split up into two or three subcategories if desired; global functions, local functions, and undefined/external functions. For details of these reporting options, refer to the "Detach globals" and "Detach undefined" options under REPORT OPTIONS. By default, a function summary follows the cross-reference, including a listing of symbols and functions declared and used by the function. The "Function summary" option under REPORT OPTIONS can be used to disable this feature. Keep in mind that some apparently unused symbols in the summary may have been declared for use as dynamic free variables in a called function, so refer to the warnings report and its cross-reference to determine it's actual use. In parentheses following the function name, local functions are identified with fully-qualified hierarchical function names. Global functions are simply marked global. Hierarchical names are based on declared scope. The function name is prefixed by its parent function, which is prefixed by the parent's parent and so forth until a global function is reached. Periods serve as dividers. The hierarchical names are useful to differentiate between identically named functions which have different ancestry and scope. The following example cross-reference is taken from an analysis of the sample BUB.LSP file. bubble (global) def in 36 cal in C:BUB 52 uses syms: dimsc item pt C:BUB (global) def in 44 uses funs: bubble leader decs syms: dimsc i pt s uses syms: i item s drawln (leader.drawln) dec in leader 5 def in leader 8 cal in leader 33 cal in drawln 18 uses funs: drawln uses syms: dimsc i pt pt2 leader (global) def in 5 cal in C:BUB 51 decs funs: drawln uses funs: drawln decs syms: i pt2 uses syms: dimsc pt pt2 When multiple files are analyzed, the file name precedes the parent function names for each listed usage. 8.12 CROSS-REFERENCE OF USER DEFINED SYMBOLS --------------------------------------------- User-defined symbols are those not explicitly defined as functions (with defun statements) and not belonging to AutoLISP's reserved subr and symbol set. These symbols are listed in alphabetical order. Each symbol has a separate cross-reference for the parent functions and line numbers in which it is declared, referenced and set. The symbol's scope is determined by where and if it is declared (see the preceding DECLARATIONS AND SYMBOL SCOPE section for a discussion of scope). ALLY uses dynamic scoping rules for duplicate named local symbols, properly treating them as separate and distinct symbols. Instances of dynamic free variable usage (called functions using the calling function's local variables) are noted and marked by asterisks prefixing the "set in" and "ref in" notices. The symbol cross-reference can be split up into two subcategories if desired; global functions and local functions. For details of these reporting options, refer to the "Detach globals" option under REPORT OPTIONS. The format of the cross-reference is similar to the function report section, and symbols are either marked global or with a hierarchical name. In the sample symbol listing which follows (from an analysis of BUB.LSP), note that two unrelated symbols share the name i. This is perfectly acceptable, since the symbols have different scopes as their hierarchical names indicate. dimsc (c:bub.dimsc) dec in C:BUB 44 *ref in drawln 10 *set in leader 22 *ref in leader 27,29 *ref in bubble 38,40 i (c:bub.i) dec in C:BUB 44 set in C:BUB 48 ref in C:BUB 49 i (leader.i) dec in leader 5 *set in drawln 12,15 *ref in drawln 12 item (global) ref in bubble 40 set in C:BUB 47,49 ref in C:BUB 47 pt (c:bub.pt) dec in C:BUB 44 *set in drawln 12,15 *ref in drawln 10,11,12,15,16 *set in leader 23,29 *ref in leader 24,27,29 *ref in bubble 38,39,40 pt2 (leader.pt2) dec in leader 5 set in leader 24 ref in leader 29 *set in drawln 12,16 *ref in drawln 10,11,15 s (c:bub.s) dec in C:BUB 44 set in C:BUB 47 ref in C:BUB 48 Like user defined functions, when multiple files are analyzed the file name precedes the parent function names of each symbol usage. 8.13 CROSS-REFERENCE OF RESERVED LISP SUBRS AND SYMBOLS -------------------------------------------------------- This optional section of ALLY's report will alphabetically list AutoLISP reserved subrs and symbols used by the analyzed file. Each reserved symbol has a separate cross-reference for the parent functions and line numbers in which it is referenced, called or set. The constants pi, T, and nil should only be referenced, *error* can be set, and generally all remaining subrs are only to be called. A short sample, excerpted from an analysis of BUB.LSP, follows. > cal in drawln 10 angle cal in leader 29 command cal in drawln 11 cal in leader 27 cal in bubble 38 Generally, one has no reason to include this section in the Analyzer reports. Cross-referencing reserved symbols adds to ALLY's memory overhead and increases the size of report files and documents. In some circumstances it can prove useful, however, such as confirming AutoLISP version compatibility. 8.14 PROGRAM LISTING --------------------- This section of the report contains a source listing of each AutoLISP file analyzed. ALLY numbers each line of the files for the purpose of cross-referencing functions and symbols. Embedded Tabs (ASCII 9) are expanded to the number of spaces set in the ALLY Workbench (the default is 8 spaces). All other control characters (ASCII 0 to 31) are represented by a carat symbol followed by the control letter. For example, a backspace character (ASCII 8) is displayed and printed as ^H. This allows you to identify the inclusion of any of these normally unprintable characters in the file. Control characters are sometimes included intentionally, but can occur from using a word processor in its proprietary document mode rather than ASCII mode. Appendix A of this manual contains an ASCII table which lists the control characters. The listing is formatted to the column width you specify in the ALLY Workbench. Lines whose length exceed the specified page width are broken at the nearest delimiter. The remaining portion of the line is wrapped underneath. For better readability, the wrapped portion is indented to the same column of indentation as the line above. This is illustrated by line number 17 in the following sample. The following example (an invented example, not from BUB.LSP) illustrates the features of ALLY program listings: 16 (defun *error* (str1) 17 (if (and str1 (/= str1 "console break") (/= str1 "Function canceled")) 18 (prompt (strcat "\n^GError: " str1)) 19 ) 20 (grtext) 21 (princ) 22 ) Note the ^G on line 18 above. It is an embedded BEL character (ASCII 7) to beep the computer's speaker (this method of beeping, incidentally, is not effective with all hardware). 8.15 ANALYZER SCREEN OUTPUT ---------------------------- When you choose to send the report to screen, the Analyzer simply redirects its normal printer/file write operations to the console device. Because there is no disk or printer I/O involved, you get the report fast. The downside is that due to the interception method employed, you cannot cursor backwards to see text that has scrolled or paged off screen. If you need greater viewing flexibility, send the report to your editor or browser instead. From Setup's Execution Options screen, you can configure ALLY to use 43/50-line EGA/VGA display or extended text modes for the screen output. Here is a summary of the commands available with report output to screen. [A] or [Esc] Aborts browsing and returns the Workbench. [Down] . . . Cursor key, displays the next line of the report. [PgDn] . . . . Displays the next screen page of the report. [N] . . . . . Nonstop. The report scrolls continuously until the end of file or a key is pressed. [MouseRight] . The right mouse button is the same as pressing the [Down] cursor. [MouseBoth] . Both mouse buttons pressed simultaneously together is the same as pressing [Esc]. [MouseLeft] . The left mouse button is the same as pressing the [PgDn] key. 9.0 P R O B L E M S A N D E R R O R M E S S A G E S ============================================================== This section illustrates some of the problems which can occur when initially setting up ALLY, or after making changes to your disk directories or hardware. You should begin by first reviewing the INSTALLATION and SETUP OPTIONS chapter of this manual, then trying some of the solutions below before calling for technical support. Chances are, the solution is simple, often accomplished by merely reconfiguring or reinstalling ALLY. 9.1 ALLY FAILS TO RUN ---------------------- Problems which may occur when using ALLY from AutoCAD are described in this section, along with suggested corrective actions. Error messages pertaining to lack of memory are more likely to surface with AutoCAD R10 and R11 than with R12. If ALLY fails, always flip to the text screen to read the reported error message. "Unknown command" or "bad command or file name" If one of these messages occur after entering the ALLY command in AutoCAD, either ALLY has been incompletely installed or changes have been made to your system (such as upgrading AutoCAD or adding another 3rd party application) which effected ALLY's installation. To correct this, just reinstall with ALLY's INSTALL program. Your existing ALLY setup options will be preserved. "EXEC failure" or "Cannot execute ALLYWB.EXE" When DOS reports one of these messages under AutoCAD, there is not enough memory to get ALLY started, and you must make more available. See the following section, INCREASING CONVENTIONAL DOS MEMORY. "Insufficient memory..." or "Out of memory..." ALLY may report one of these messages when analyzing or browsing an unusually large or complex file. You can lessen ALLY's memory requirements in several ways; setting a reduced level depth for the Function Call Hierarchy, disabling the X-ref Reserved option, and/or reducing the Read Buffer size. You will rarely need to cross-reference reserved symbols, and a large Read Buffer can usually be made smaller. The only use for a buffer larger than 1K is to error check Kelvinated or "squeezed" files, and their reports have limited usefulness. If you do not wish to give up the above mentioned ALLY features, or if the insufficient memory problem occurs with your user-installed editor, browser or other external program, the solution is to increase the memory available to ALLY. One such solution is to run ALLY directly from DOS, where it can use all available memory. There are several solutions to increase the availability of conventional memory. If you are using a 386 version of AutoCAD, continue on to the next section, INCREASING CONVENTIONAL DOS MEMORY. If you are using a 286 version of AutoCAD R10 or R11, you must first tell AutoCAD the amount of additional memory to release to ALLY. This is done by increasing the memory reserve figure in the ALLY command line in your ACAD.PGP file. Try raising the memory reserve 25000 bytes at a time, retesting after each change. ALLY3,C:\ALLY\ALLYWB,305000,,4 Since AutoCAD can not give any more than it receives, you may also need to use the techniques described in the section INCREASING CONVENTIONAL DOS MEMORY, below. 9.2 INCREASING CONVENTIONAL DOS MEMORY --------------------------------------- A significant amount of conventional memory is often consumed by drivers and TSR programs. Use a memory manager such as EMM386, QEMM, 386^MAX, or NETROOM to load them into upper memory blocks. If you are using MS-DOS 5 or higher, load DOS itself high for a significant gain. If a TSR is not absolutely necessary, consider either unloading it prior to starting AutoCAD or eliminating it entirely. If you are running AutoCAD 386 R11, you can use Autodesk's NEWDX utility to update the R11 Phar Lap DOS Extender with a newer, smaller kernel version if you have not already done so. The NEWDX program and documentation file is shipped with R11 revision c2, and is available from dealers and CompuServe's ACAD forum. Regardless of the version of AutoCAD being used, there are shell utilities which can recover the memory AutoCAD holds back for itself when it shells out to applications such as ALLY. There are at least two commercial shell utilities which will do the job, and one named SHROOM which Autodesk ships with R11 and R12. A shareware version of the SHROOM utility can be found in CompuServe's ACAD forum. If you use a 286 version of AutoCAD, be sure to increase ALLY's memory reserve in your ACAD.PGP file as described in the previous section. 9.3 USER-INSTALLED PROGRAM FAILS TO RUN ---------------------------------------- If a user-installed program fails to execute from ALLY, first check the ALLY setup options to see that the program is properly installed with the correct path and name, and that all ALLY's special symbols and file aliases are properly used. If the installation is correct, the probable cause of the failure is insufficient memory, and you will need to substitute a smaller program or make more memory available to ALLY, as described in previous sections. 9.4 VIDEO PROBLEMS ------------------- On AutoCAD 386 systems with certain video accelerators and/or third-party protected-mode display-list drivers (ADI P386 drivers), problems may occur when running ALLY in 43/50 line EGA/VGA or extended text modes. Potential problems ranging from random garbage displayed on AutoCAD's screen to system lockups are due to the inability of the video system to handle video mode changes from AutoCAD's shell. To avoid this, try a different AutoCAD video driver or set ALLY's "Allow from ACAD" video option to NO. If you happened to select a user video mode which locks up ALLY even when run from DOS, you can run ALLYSU.EXE directly from DOS to change it. A P P E N D I X A - A S C I I T A B L E =================================================== +----------------+-----------+-----------+-----------+ | DEC CTRL NAME | DEC CHAR | DEC CHAR | DEC CHAR | |----------------|-----------|-----------|-----------| | 0 ^@ NUL | 32 | 64 @ | 96 ` | | 1 ^A SOH | 33 ! | 65 A | 97 a | | 2 ^B STX | 34 " | 66 B | 98 b | | 3 ^C ETX | 35 # | 67 C | 99 c | | 4 ^D EOT | 36 $ | 68 D | 100 d | | 5 ^E ENQ | 37 % | 69 E | 101 e | | 6 ^F ACK | 38 & | 70 F | 102 f | | 7 ^G BEL | 39 ' | 71 G | 103 g | | 8 ^H BS | 40 ( | 72 H | 104 h | | 9 ^I HT | 41 ) | 73 I | 105 i | | 10 ^J LF | 42 * | 74 J | 106 j | | 11 ^K VT | 43 + | 75 K | 107 k | | 12 ^L FF | 44 , | 76 L | 108 l | | 13 ^M CR | 45 - | 77 M | 109 m | | 14 ^N SO | 46 . | 78 N | 110 n | | 15 ^O SI | 47 / | 79 O | 111 o | | 16 ^P DLE | 48 0 | 80 P | 112 p | | 17 ^Q DC1 | 49 1 | 81 Q | 113 q | | 18 ^R DC2 | 50 2 | 82 R | 114 r | | 19 ^S DC3 | 51 3 | 83 S | 115 s | | 20 ^T DC4 | 52 4 | 84 T | 116 t | | 21 ^U NAK | 53 5 | 85 U | 117 u | | 22 ^V SYN | 54 6 | 86 V | 118 v | | 23 ^W ETB | 55 7 | 87 W | 119 w | | 24 ^X CAN | 56 8 | 88 X | 120 x | | 25 ^Y EM | 57 9 | 89 Y | 121 y | | 26 ^Z SUB | 58 : | 90 Z | 122 z | | 27 ^[ ESC | 59 ; | 91 [ | 123 { | | 28 ^\ FS | 60 < | 92 \ | 124 | | | 29 ^] GS | 61 = | 93 ] | 125 } | | 30 ^^ RS | 62 > | 94 ^ | 126 ~ | | 31 ^_ US | 63 ? | 95 _ | 127 DEL | +----------------+-----------+-----------+-----------+ A P P E N D I X B - P R I N T E R C O M M A N D S ============================================================= The following are tables of printer control codes and escape sequences for dot-matrix and laser printers. These are not full command listings, just a few you may find useful to execute before or after printing ALLY's reports. These are provided only as a quick reference source, you should consult your printer manual for details and commands specific to your hardware. Use decimal ASCII codes for ALLY's printer setup and reset strings. Letters in the escape sequences are case sensitive, use ASCII codes for upper or lower case as indicated. The ASCII table in Appendix A will help you translate commands into the decimal ASCII strings required by ALLY. To send multiple commands in the strings, simply chain them together, separating each ASCII code with commas. For example: 27,79,15,27,48 ALLY reports are formatted for mono-spaced fonts, thus will be much less readable with proportional fonts. If your printer defaults to a proportional font, be sure to include a setup command to change to a fixed, mono-spaced font. If necessary, you can restore your default font in ALLY's reset string. DOT-MATRIX PRINTERS ------------------- The listed dot-matrix printer functions are valid for nine-wire IBM, Epson, and compatibles such as Panasonic. Where command functions differ for the three brands mentioned, the brand identification is shown in square brackets: I=IBM, E=Epson, P=Panasonic. Some of the dot-matrix commands will function only when certain printer modes or switches are set. Although many character modes have both on and off commands, others have no off command--they are turned off when another mode is selected. The following is an analysis of sample ALLY dot-matrix setup and reset strings: compressed mode on | set 1/8" line spacing | | +-+ +----+ Setup: 15, 27, 48 compressed mode off | set 1/6" line spacing | | +-+ +----+ Reset: 18, 27, 50 In the dot-matrix printer table, n represents a decimal number (the actual number itself, not its ASCII value) between 0 and 255, inclusive. ------------------------------------------------------------------------------- Code or Decimal Dot-matrix Printer Sequence ASCII Function ------------------------------------------------------------------------------- LF 10 Line feed FF 12 Form feed (to next top of form) CR 13 Carriage return SI 15 Compressed mode on DC2 18 Compressed mode off Esc SI 27,15 Compressed mode on [E, P] Esc 0 27,48 Set 1/8 inch line spacing Esc 1 27,49 Set 7/72 inch line spacing Esc 2 27,50 Set 1/6 inch line spacing (standard) Esc 3 n 27,51, n Set n/216 inch line spacing (example: 27,51,21 sets 21/216"spacing) Esc 4 27,52 Italic mode on [E, P] Esc 5 27,53 Italic mode off [E, P] Esc @ 27,64 Initialize printer [E, P] Esc E 27,69 Emphasized mode on Esc F 27,70 Emphasized mode off Esc G 27,71 Double-strike mode on Esc H 27,72 Double-strike mode off Esc M 27,77 Elite pitch on Esc N n 27,78, n Skip n lines over perforation (example: 27,78,8 skips 8 lines) Esc O 27,79 Skip-perforation off Esc P 27,80 Pica pitch on [I, P] Elite pitch off [E] Esc n 27,110 Set letter quality print mode [P] Esc z 27,122 Select letter quality/draft [E, I] LASER PRINTERS -------------- The following laser printer escape sequences are for HP laserjet compatible printers supporting PCL commands. When combining commands, if the first two characters after Esc are the same in adjacent commands, the command string can be shorted by changing the leading and any intermediate command's last character to lower case and dropping the matching characters from following commands. The final character must remain upper case at the end of the combined command--at the termination of the string or before a new escape sequence is started. Generally, commands must be issued in the same order they are presented in the table. For example, Esc ( s 0 S + Esc ( s 0 B + Esc ( s 3 T = Esc ( s 0 s 0 b 3 T 27,40,115,48,83 27,40,115,48,66 27,40,115,51,84 27,40,115,48,115,48,98,51,84 The following is an analysis of a sample laser printer setup string: 5.45/48" line spacing PC-8 symbols fixed spacing +----------------------+ +------------+ +--------------+ Setup: 27,38,108,53,46,52,53,67, 27,40,49,48,85, 27,40,115,48,112, medium line printer 16.67 chars/inch 8.5 points upright weight typeface +----------------+ +----------+ +----+ +---+ +---+ ... 49,54,46,54,55,104, 56,46,53,118, 48,115, 48,98, 48,84 In the laser printer table, # and #...# represent the ASCII values for each digit of the required number. For example, 5.45 is represented as 53,46,52,53 ------------------------------------------------------------------------------- Code or Decimal Laser Printer Sequence ASCII Function ------------------------------------------------------------------------------- LF 10 Line feed FF 12 Form feed (to next top of form) CR 13 Carriage return Esc E 27,69 Reset printer Esc & l # C 27,38,108,#...#,67 Set #/48 in. vertical line spacing (example: 27,38,108,53,46,52,53,67 sets a 5.45/48" spacing, equaling 88 lines/page) Esc & l # D 27,38,108,#...#,68 Set # lines/inch vertical spacing, valid spacings are 1, 2, 3, 4, 6, 8, 12, 16, 24, 48 (example: 27,38,108,56,68 sets 8 lines/in) Esc ( 10 U 27,40,49,48,85 Set PC-8 primary symbol set Esc ( 11 U 27,40,49,49,85 Set PC-8 D/N primary symbol set Esc ( s 0 P 27,40,115,48,80 Set fixed spacing (mono-spacing) Esc ( s # H 27,40,115,#...#,72 Set # characters/inch horizontal pitch (example: 27,40,115,49,54,54,46,54,55,72 sets 16.67 characters per inch) Esc ( s # V 27,40,115,#...#,86 Set # point size character height (example: 27,40,115,56,86 sets 8 point) Esc ( s 0 S 27,40,115,48,83 Sets upright style Esc ( s -3 B 27,40,115,45,51,66 Set light stroke weight Esc ( s 0 B 27,40,115,48,66 Set medium stroke weight Esc ( s 3 B 27,40,115,51,66 Set bold stroke weight Esc ( s 3 T 27,40,115,51,84 Set courier typeface Esc ( s 0 T 27,40,115,48,84 Set line-printer typeface Esc ( # X 27,40,#...#,88 Select primary Font with ID # (varies) A P P E N D I X C - S T R I N G - E M B E D D E D C O D E ======================================================================= The ALLY Analyzer reads and analyzes AutoLISP code embedded in the action-expression strings of action_tile and new_dialog function calls. This support, however, is limited to literal strings within the function calls, action-expression strings referenced by variable or further masked in a nested function such as strcat are not analyzed. To ensure ALLY analyzes all AutoLISP code, we recommend you avoid these practices if at all possible. Although our driving philosophy is that programmers should not have to modify their source code in order to use ALLY, we have provided for a special function, named ally_cat. The Analyzer treats all double-quoted ally_cat string arguments as AutoLISP code. This can be used when action-expression string concatenation cannot be avoided or if the string must be referenced by variable, and also for any custom routines you may have which embed AutoLISP expressions into strings. Ally_cat is not a user-defined function, but an alias you create for the standard AutoLISP strcat function. You must establish the alias early in your program, prior to calling ally_cat. This is done with the setq function as shown below. (setq ally_cat strcat) The ally_cat symbol can be either global or local, and will not prohibit strcat from being used for normal string operations. To break the established alias and dispose of the symbol after use, simply set ally_cat to nil. The syntax for ally_cat is the same as strcat (since it is strcat), taking one or more string arguments. Use ally_cat wherever you have string-embedded AutoLISP code the Analyzer cannot reach, but do not use it for non-code strings or nest ally_cat calls. ALLY considers ally_cat itself to be a reserved subr and reports instances of its use along with strcat and other built-in functions. The following examples show how ally_cat can be used effectively. BEFORE AFTER (setq ally_cat strcat) (setq expr "(dosize)") (setq expr (ally_cat "(dosize)")) (action_tile "pd" (action_tile "pd" (strcat "(mode_tile ptmode 4)" (ally_cat "(mode_tile ptmode 4)" "(setq ptmode $key)" "(setq ptmode $key)" "(mode_tile ptmode 4)" "(mode_tile ptmode 4)" ) ) ) ) (action_tile "pdsize" expr) (action_tile "pdsize" expr) (action_tile "accept" "(p_set)") (action_tile "accept" "(p_set)") (setq ally_cat nil)