Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / ALLY211.ZIP / ALLY.DOC next >

Wrap

Text File | 1992-09-16 | 127.4 KB | 3,237 lines

---------------------------------------- ALLY - A LISP ANALYZER Version 2.0 User's Manual ---------------------------------------- Copyright 1990, 1991 Steve Waskow ALL RIGHTS RESERVED _______ ____|__ | (R) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER ---------------------------------------- Wasco Technical Software 1211 Grand Junction Drive Katy, TX 77450 ---------------------------------------- Phone/FAX: (713) 392-1359 CompuServe: 72020,2031 ------------------------------------------------------------ DISCLAIMER AND LIMIT OF LIABILITY ------------------------------------------------------------ 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. ------------------------------------------------------------ COPYRIGHT NOTICE AND TRADEMARKS ------------------------------------------------------------ The ALLY software programs and documentation are: Copyright 1990, 1991 Steve Waskow Wasco Technical Software All rights to the ALLY software programs and this document are reserved by Steve Waskow and Wasco Technical Software. AutoCAD & AutoLISP are registered trademarks of Autodesk, Inc. Other brand and product names mentioned herein are trademarks or registered trademarks of their respective holders. ------------------------------------------------------------ CREDITS ------------------------------------------------------------ Special thanks to ALLY beta testers Antonio Fernandes, Howard Johnson, Eric Michalowsky, David Pitzer and Trent Riley. These gentlemen have provided constructive criticism, numerous suggestions, and precious support throughout ALLY's lengthy development and evolution cycle. Thanks guys, I couldn't have done it without you. Steve Waskow, 1991 ALLY - A Lisp Analyzer 1 Version 2.0 User's Manual ------------------------------------------------------------ TABLE OF CONTENTS ------------------------------------------------------------ INTRODUCTION ............................................. 3 INSTALLATION ............................................. 4 System Requirements .................................... 4 File Directory ......................................... 4 Automatic Installation ................................. 4 Manual Installation (Optional) ......................... 4 Using Expanded Memory (Optional) ....................... 5 Adjusting the ACAD.PGP Memory Reserve .................. 6 First Time Users ....................................... 6 ALLY DATA ENTRY SCREENS AND EDITING KEYS ................. 7 Mouse Hot Spots ........................................ 9 ALLY SETUP OPTIONS ...................................... 10 Install User Programs ................................. 11 Define Page ........................................... 13 Report Options ........................................ 15 Execution Options ..................................... 17 Printer Setup ......................................... 19 About ALLY ............................................ 20 THE ALLY WORKBENCH ...................................... 21 File/Destination ...................................... 21 File Selection ........................................ 23 Workbench Commands .................................... 25 THE ALLY CHECKER ........................................ 29 THE ALLY ANALYZER ....................................... 31 Analyzing Multiple Files .............................. 32 Declaration and Symbol Scope .......................... 33 Warnings Reported ..................................... 37 File Hierarchy of User Defined Functions .............. 39 Function Call Hierarchy - Dynamic Scope ............... 40 Cross-reference of User Defined Functions ............. 41 Cross-reference of User Defined Symbols ............... 42 Cross-reference of Reserved Subrs and Symbols ......... 43 Program Listing ....................................... 44 Analyzer Screen Output ................................ 45 PROBLEMS AND ERROR MESSAGES ............................. 46 Problems with ACAD.LSP and ACAD.PGP ................... 46 Problems with ALLY Executable Files ................... 47 APPENDIX A - ASCII TABLE ................................ 49 APPENDIX B - PRINTER COMMANDS ........................... 50 INDEX ................................................... 52 ALLY - A Lisp Analyzer 2 Version 2.0 User's Manual ------------------------------------------------------------ INTRODUCTION ------------------------------------------------------------ ALLY is a programmer's workbench, code checker and analyzer for AutoLISP, the AutoCAD LISP programming language. The ALLY Checker and Analyzer assist you in debugging and documenting AutoLISP source code. The ALLY Workbench integrates your text editor and other programs to create a personalized programming environment, accessible from and interactive with AutoCAD. The ALLY Analyzer generates a comprehensive cross-reference of variables, constants, functions and subroutines, and a full function call hierarchy. Each symbol is identified by line number and scope, and categorized as a call, declaration, definition, reference, or setting. ALLY's analysis is useful in identifying symbol scopes, interactions and dependencies, declared but unused symbols, duplicate definitions and function side effects, and provides extensive error checking. You can analyze several LISP files together to check program compatibility. The ALLY Checker uses color coding to provide a convenient visual check of mismatched parentheses, misplaced or missing string quotes, and missing comment semicolons. The size of files which ALLY can handle is limited only by available memory. ALLY reads individual lines up to 64 kilobytes in length, and safely prints any embedded control characters. The Workbench's text editor is your own - ALLY links your favorite text editor to the Workbench, making it available at the press of a key. ALLY also links your text file browser and up to eight more of your favorite tools and utilities, assigning each an execution key. ALLY shrinks itself to less than 4K when shelling to DOS and executing external programs. The ALLY Workbench integrates these tools in a tidy package with mouse support, point-and-shoot file selection, and shell for executing DOS commands and external programs. ALLY can be used from DOS or run from within AutoCAD. When run from AutoCAD, ALLY can load your programs into AutoLISP with a single keystroke. ALLY - A Lisp Analyzer 3 Version 2.0 User's Manual ------------------------------------------------------------ INSTALLATION ------------------------------------------------------------ This chapter contains important information on system requirements and installation. Please read this section completely before beginning your ALLY installation. SYSTEM REQUIREMENTS ------------------------------------------------------------ ALLY's requirements are basically the same as DOS versions of AutoCAD. ALLY requires an IBM XT, AT, PS/2 or true compatible with 640K RAM, hard disk, monochrome or color display, and MS/DOS 3.1 or higher. ALLY can be run from DOS as a stand-alone product, or run from within AutoCAD. The ALLY AutoCAD interface requires AutoCAD Release 9 or later, and a shell space of 240000 or more bytes - depending on your usage. FILE DIRECTORY ------------------------------------------------------------ ALLY's files can either be placed into the drive/directory in which your AutoCAD executable program files are kept, or into any support directory pointed to by AutoCAD's ACAD environment variable. AutoCAD R11+ allows more than one directory in the ACAD path, so you can create a new ALLY directory if you wish. AUTOMATIC INSTALLATION ------------------------------------------------------------ To install ALLY, run the installation program ALLYIN.EXE. Just type "ALLYIN" at the DOS prompt and follow the on-screen instructions. ALLYIN installs the ALLY files and updates your ACAD.LSP and ACAD.PGP. As an alternate to using ALLYIN, you can install ALLY manually with DOS and an ASCII text editor. Manual installation instructions are given below. MANUAL INSTALLATION (OPTIONAL) ------------------------------------------------------------ 1. Copy the ALLY files ALLYWB.EXE, ALLYSU.EXE, ALLYAN.EXE, ALLYCK.EXE, ALLY.BAT, ALLY.LSP and ALLYXM.SCR into the ALLY directory you have chosen (see FILE DIRECTORY above). 2. If you have registered ALLY, use an ASCII text editor to edit the newly installed ALLY.BAT file. Replace the dummy registration code "+RegCode" with your assigned code. ALLY - A Lisp Analyzer 4 Version 2.0 User's Manual 3. Use your text editor again, this time to edit your ACAD.PGP file. Your ACAD.PGP should be located in either your AutoCAD executable directory or a support directory. Create one if none exists. Add the following line: ALLY!, ALLYWB +RegCode, 240000, , 0 If ALLY is installed in a directory other than your AutoCAD executable directory which is not on your DOS PATH, prefix "ALLYWB" with its directory path. Also, if you are a registered user, you should replace the dummy registration code "+RegCode" with your assigned code. 4. Add ALLY.LSP to your ACAD.LSP file. Like ACAD.PGP, it will be located in either your AutoCAD executable directory or a support directory. Create one if none exists. Use an ASCII text editor to insert the ALLY.LSP file into the bottom of ACAD.LSP. Do not attempt to edit ACAD.LSP if it is encrypted. If you see "AutoCAD PROTECTED LISP file" as the file's first line, exit the editor without saving the file - you will need to load ALLY.LSP as needed with AutoCAD's LOAD command. USING EXPANDED MEMORY (OPTIONAL) ------------------------------------------------------------ If you have adequate expanded memory (EMS) available, ALLY will automatically use it instead of a disk swap file when executing your external programs. Swapping to EMS is faster, but file swapping on a decent hard disk is more than adequate. To use EMS, ALLY needs five 16K EMS pages (5 EMS pages = 81920 bytes = 80K kilobytes = 0x14000 bytes hexadecimal). To set aside EMS for ALLY with non-386 versions of AutoCAD, check your AUTOEXEC.BAT file or your AutoCAD start-up batch file for a line which sets AutoCAD's ACADLIMEM environment variable. If there is none, add the following line: SET ACADLIMEM=-5 If you have ACADLIMEM set to ALL, change it to -5. If you have ACADLIMEM set to a positive value, decrease it by the equivalent of 5 EMS pages. If ACADLIMEM is set to a negative value, increase it by the equivalent of 5 EMS pages. To set aside EMS for ALLY with AutoCAD 386 using VCPI-style expanded memory, use AutoCAD's CFIGPHAR.EXE program or the -maxvcpi switch of AutoCAD's CFIG386.EXE program to limit AutoCAD to 81920 bytes less than its current expanded memory usage. ALLY - A Lisp Analyzer 5 Version 2.0 User's Manual AutoCAD defaults to using all expanded memory, so check your current configuration and switch settings before making modifications. Refer to your AutoCAD Installation and Performance Guide for details specific to your hardware and AutoCAD version. ADJUSTING THE ACAD.PGP MEMORY RESERVE ------------------------------------------------------------ Because the requirements of your installed external programs and the size and number of files you analyze are variables, we cannot anticipate precisely the amount of memory required. Some trial and error may be required. You can increase available memory in non-386 DOS versions of AutoCAD by editing your ACAD.PGP file, changing the 240000 byte memory reserve field in the "ALLY!" command line to a higher value. Try incremental increases of 25000 bytes until ALLY functions with your largest AutoLISP files. Your text editor may be a large consumer of memory. If you already successfully run it from AutoCAD, try using its ACAD.PGP file memory reserve figure plus about 4000 bytes for ALLY. You must exit and reenter the AutoCAD drawing editor after each change to ACAD.PGP. These and other methods of dealing with insufficient memory problems, including solutions to AutoCAD 386 memory problems, are discussed further in the PROBLEMS AND ERROR MESSAGES chapter at the back of this manual. FIRST TIME USERS ------------------------------------------------------------ Although no trouble is anticipated, in keeping with the spirit of "better safe than sorry", we suggest you save your drawing prior to executing ALLY the first few times you try it. This is especially wise if you have a highly customized system. If your text editor and other 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. ALLY - A Lisp Analyzer 6 Version 2.0 User's Manual ------------------------------------------------------------ ALLY DATA ENTRY SCREENS AND EDITING KEYS ------------------------------------------------------------ The ALLY Workbench and Setup programs have a series of data entry screens for configuration items and other user input. These screens are simple to edit. Use your cursor keys or mouse to move about the screen to add or change entries. The active field is highlighted. Fields can be picked with a mouse by moving the mouse cursor into the field and pressing the left mouse button. 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 (a small solid rectangle) in the upper left hand corner of the window. These editing keys are common to the ALLY Workbench and Setup programs. Key functions may differ in other parts of ALLY, other chapters of the manual describe keys specific to the ALLY Checker and Analyzer. [Enter] .... (also known as [Return]) Enter data and cursor down a data entry screen, or pick the highlighted item of a selection list. [Left] ..... Cursor key, moves the cursor left one space. [Right] .... Cursor key, moves the cursor right one space. [Up] ....... Cursor key, moves up one line. [Down] ..... Cursor key, moves down one line. [^Left] .... Control-Left cursor moves the cursor left one word. When editing a file name or directory path, backslash divisions are word breaks. [^Right] ... Control-Right cursor moves the cursor right one word. When editing a file name or directory path, backslash divisions are word breaks. [Home] ..... Moves cursor to the first character of an entry field or the top of a selection list. ALLY - A Lisp Analyzer 7 Version 2.0 User's Manual [End] ...... Moves cursor to the last character of an entry field or the bottom of a selection list. [PgUp] ..... Moves to the top of a data entry screen or displays the previous page of selections. [PgDn] ..... Moves to the bottom of a data entry screen or displays the next page of selections. [Ins] ...... The Insert key toggles the insert/overwrite mode. [Esc] ...... Use the Escape key to undo any changes to the current data entry field. [Esc] also exits menus and aborts pending commands and active processes. [BkSp] ..... The Backspace key deletes the character to the immediate left of the cursor. [Del] ...... The Delete key deletes the character directly above the cursor. [^End] ..... Control-End deletes text from the cursor position to the end of the entry. [^Home] .... Control-Home deletes text from the first character of the entry to the cursor position. [Spacebar] . Toggles the entry of a highlighted fixed response field, such as a YES/NO field. [MouseRight] The right mouse button performs the same function as the [Spacebar] for fixed responses. [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. See the following MOUSE HOT SPOTS section. ALLY - A Lisp Analyzer 8 Version 2.0 User's Manual MOUSE HOT SPOTS ------------------------------------------------------------ You can move around and execute many commands and functions by picking mouse sensitive hot-spots with your left mouse button. 1. Data entry screen fields. Pick any field to move the cursor and highlight bar into it. 2. Menu window choices. Choose a menu item by picking it. 3. [F1] through [F10] commands and [^F1] through [^F8] user programs. Picking an item on the top screen menu executes the command or program. 4. Exit window buttons. Pick the rectangle in the top left hand corner of a window border to exit the window. 5. Fixed response options, such as YES/NO and NAME/TIME/SIZE. Reply to data entry fields and prompts which require a fixed response by picking the appropriate answer from the message prompt in the lower right hand part of the screen. 6. Filenames in the file selection window. Picking an un-highlighted file name moves the highlight bar to the picked position. Picking a highlighted name selects it. 7. File selection window scroll bar. Pick a point along the scroll bar relative to the position of the file list you wish to move to. 8. File selection window Up and Down arrows. Pick these to cursor through the list of file names. ALLY - A Lisp Analyzer 9 Version 2.0 User's Manual ------------------------------------------------------------ ALLY SETUP OPTIONS ------------------------------------------------------------ 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(ions) in the top command menu line. The Options screen presents a main menu of options. o------- Options --------+ | Install User Programs | | Define Page | | Report Options | | Execution Options | | Printer Setup | | 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. ALLY - A Lisp Analyzer 10 Version 2.0 User's Manual 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 [F7]/[Alt-B], the editor to [F8]/[Alt-E], and other user programs to [Ctrl-F1] through [Ctrl-F8]. o-------------- Install User Programs --------------+ | F7 Browser: c:\util\list.com ] | | F8 Editor : C:\ED\EDWIN.COM ] | |^F1 Program: @d:\acad\adesk\kelv [ > e:\;.k | |^F2 Program: D:\ACAD\ADESK\LB.EXE -w80 ] [.NEW | |^F3 Program: copy ] ? | |^F4 Program: dir ch????.lsp | |^F5 Program: D:\PRT\LJBOOK * | |^F6 Program: del *.bak | |^F7 Program: | |^F8 Program: | +---------------------------------------------------+ Commands and external programs install in the same fashion, except internal DOS commands (such as DIR) have no path or file extension. If your program's directory is listed in your PATH statement (check your AUTOEXEC.BAT file), you can simply enter the program's file name (example: EDWIN). If its directory is not in the PATH statement, prefix the program name with its full directory path (example: C:\ED\EDWIN). If the program must execute from within its own directory, prefix the path with an ampersand (example: @C:\ED\EDWIN). The ampersand forces a directory change to the listed directory before program execution, and back after. If you give the full path name of your program AND the file extension (example: C:\ED\EDWIN.COM), ALLY will execute it directly, without first loading a copy of the DOS command interpreter (COMMAND.COM). With many DOS versions, this makes as much as 3.5 kilobytes more memory available to the program. List any required command line parameters behind the program name. 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. Spaces before and after the question mark prevent ALLY from confusing it with a DOS wildcard character. The command line editor positions the cursor at the position of the question mark. ALLY - A Lisp Analyzer 11 Version 2.0 User's Manual ALLY uses other special symbols as filename aliases. When you insert a right bracket (]) into the command, ALLY converts it to the full path and filename of the selected LISP file. A left bracket ([) converts to the full path and LISP filename less the file extension. A semicolon (;) converts to the LISP filename less both path and extension. An asterisk (*) converts to the full path and filename of the Analyzer report file. These symbols allow you to build variable command lines for your programs which require input and output filenames. All special symbols except the semicolon must be preceded by a blank space, and all special symbols except the semicolon and left bracket must either be followed by a blank space or be the last character in the command. These rules prevent ALLY from confusing question mark pause symbols and asterisk report name aliases with DOS filename wildcards (examples are shown below). If in doubt, add a space and a question mark pause symbol at the end of the line to test the command. For example, if the LISP and report files are C:\MYFILE.LSP and E:\MYFILE.RPT: kelv [ > e:\;.k = kelv C:\MYFILE > e:\MYFILE.k lb -w80 ] [.NEW = lb -w80 C:\MYFILE.LSP C:\MYFILE.NEW copy ] ? = copy C:\MYFILE.LSP (& pauses for editing) dir ch????.lsp = dir ch????.lsp D:\PRT\LJBOOK * = D:\PRT\LJBOOK E:\MYFILE.RPT del *.bak = del *.bak Your editor must be capable of editing and saving files in a plain ASCII format for AutoLISP. For best results with ALLY, both the editor and browser must be capable of loading a file when the file name is placed on the command line (install these using the file name alias method described above). If not, you must load the files from within your program. Do not install TSR (Terminate and Stay Resident) programs as ALLY user programs - loading them this way can cause problems. You can use TSRs if you load them prior to executing ALLY and call them up with their usual hot keys. To maximize the amount of memory available for your programs, ALLY swaps most of its own code and data out of memory - into expanded memory if available, otherwise into a temporary hidden disk file (ALLY0000.$$$). Still, you are generally better off using small memory efficient programs rather than full-blown applications when running ALLY through AutoCAD. Some large word processors may require more memory than can readily be made available. ALLY - A Lisp Analyzer 12 Version 2.0 User's Manual 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. You can use higher values for wide carriage printers, depending on paper width and font size. 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 ----------- Enter the page length for the ALLY's report. ALLY allows settings from 44 to 32767, defaulting to 66 lines per page (a standard 11 inch long page is assumed). Adjust the page length to suit your printer and its line spacing settings. The actual number of lines printed for each page is the page length minus the top and bottom margins. Typically, dot-matrix printers default to 66 lines per page, and laser and ink jet printers default to 60. Another variable is your printer's line spacing setting - for example, using an 1/8th inch line spacing setting on a dot-matrix printer can increase the printed output to 88 lines per page. ALLY - A Lisp Analyzer 13 Version 2.0 User's Manual ALLY paginates with a title header on each page of the report. To effectively defeat ALLY's pagination, set the Page breaks option to NO and increase the Page length option to 32767 - or any value larger than the total number of lines in the report. 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. ALLY - A Lisp Analyzer 14 Version 2.0 User's Manual REPORT OPTIONS ------------------------------------------------------------ These options effect the report the ALLY Analyzer produces. o---- Report Options -----+ | File hierarchy··: YES | | Call hierarchy··: YES | | X-Ref functions·: YES | | X-Ref symbols···: YES | | X-Ref reserved··: YES | | Program listing·: YES | | Double space····: NO | | ASCII lines·····: YES | | Hard form feeds·: YES | | Page breaks·····: LIST | +-------------------------+ File hierarchy -------------- ALLY's file hierarchy is a tree structure of all user defined functions, showing their beginning and ending line numbers. Answer NO to omit this reporting. Call hierarchy -------------- The call hierarchy is a tree structure of all called and user defined functions, illustrating their dynamic scope and dependencies. Respond NO to eliminate this section from the report. The Analyzer uses less memory and executes faster with this option off, but the report is normally too valuable to exclude. X-Ref functions --------------- This is ALLY's cross-reference of all user defined functions. Like most other sections, you can turn the reporting on or off with a YES or NO response. X-Ref symbols ------------- All user defined symbols which are not functions are cross- referenced in this section. NO turns reporting off. X-Ref reserved -------------- Answer YES to have the ALLY Analyzer track and cross-reference AutoLISP's reserved symbols. These include the predefined ALLY - A Lisp Analyzer 15 Version 2.0 User's Manual constants, such s Pi, T and nil, and AutoLISP's built-in subrs (functions). ALLY categorizes each usage as called, referenced or set. This option can be useful in identifying AutoLISP version compatibility, but memory requirements and execution time of the ALLY Analyzer increase with its use. Program listing --------------- Choose YES and the ALLY Analyzer report will include a listing of the analyzed AutoLISP source files. Each line is numbered to cross-reference with the listing of functions and symbols. You can disable this option to save reporting time during debugging sessions, most text editors and browsers will identify line numbers. You should enable this and all other Analyzer options for producing final program documentation. 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. Hard form feeds --------------- If YES, ALLY inserts 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. Page breaks ----------- Enter YES, NO or LIST. The ALLY Analyzer generates up to seven sections in its reports. YES forces a page break after each of the sections - even if they are just a few lines long each. 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 allows the first six sections of the report to mix but forces a page break between program listings, allowing you to separate them to study side-by-side with the symbol cross-references. ALLY - A Lisp Analyzer 16 Version 2.0 User's Manual 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 | | Browse 2 files··: NO | | Edit 2 files····: NO | | Pause Analyzer··: NO | | Use mouse·······: YES | | 43/50 line mode·: NO | | Resistor colors·: NO | | Mono colors·····: NO | +-------------------------+ 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, TIME or SIZE. The default sorting order can be changed when selecting files. 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. ALLY - A Lisp Analyzer 17 Version 2.0 User's Manual 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. You must reload ALLY after editing this option for the change to take effect. 43/50 line mode --------------- ALLY will use EGA 43-line mode or VGA 50-Line mode display for the Checker and the Analyzer screen output when this option is on and the proper hardware is present. Resistor colors --------------- This allows you to choose the color set used in parentheses coloring 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 ----------- Answer YES to force ALLY to use monochrome (black and white) colors for its screen display, regardless of the monitor type. ALLY - A Lisp Analyzer 18 Version 2.0 User's Manual PRINTER SETUP ------------------------------------------------------------ Use the printer setup screen to select a printer port and set up printer defaults for Analyzer reports. o------------------ Printer Setup -------------------+ | 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, COM1 or COM2. 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 set to the proper baud, parity, databits, and retry mode with the DOS MODE command before executing ALLY. Printer setup ------------- This entry is optional. If you wish to send a string of control codes and/or escape sequences to your printer prior to printing ALLY Analyzer reports, use this entry to define them. Printer commands are hardware specific - although some de facto standards exist, compatibility may be limited to a subset of commands. There are differences in the codes used by different printer 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 ALLY - A Lisp Analyzer 19 Version 2.0 User's Manual 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 ABOUT ALLY ------------------------------------------------------------ Choose this menu item to display some brief information about ALLY's developer. ALLY - A Lisp Analyzer 20 Version 2.0 User's Manual ------------------------------------------------------------ THE ALLY WORKBENCH ------------------------------------------------------------ To run ALLY from either AutoCAD or DOS, just type "ALLY" and press [Enter]. 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, and the report destination. Function keys are available for configuring ALLY, for Help, and to perform actions such as executing the ALLY Analyzer, a DOS shell, your editor, file browser and other installed external programs. These command keys will be described later. 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:\ACAD11\SAMPLE\ | | Report directory: E:\ | | Lisp file name··: D:\ACAD11\SAMPLE\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 find the files it displays. 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. ALLY - A Lisp Analyzer 21 Version 2.0 User's Manual Report directory ---------------- ALLY uses the report directory, by default, as a destination for its output reports. 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 also receives the temporary report files created when the browser is named as the destination. If you have a ram disk with adequate free space, naming it as the report directory can result in a significant speed increase. You can override this default path for EDITOR and FILE destinations by prefixing the report file name with another path. 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. This name is only required when you have chosen FILE or EDITOR for the destination. ALLY will automatically fill this field, using the same name as the AutoLISP source file with a .RPT file name extension. Your chosen report directory prefixes the file name by default. You can enter a different path or name if desired. If you change the name but omit the file extension, ALLY adds .RPT by default. ALLY - A Lisp Analyzer 22 Version 2.0 User's Manual 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. When the list contains more items than can fit in the window, it scrolls as you traverse it. 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, 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 box on the scroll bar shows the position of the highlighted file relative to the length of the file list. The bold arrowheads at the top and bottom of the scroll bar are cursor hot spots. Place the mouse cursor over the arrowheads and click the left button to cursor up or down. To make bigger jumps along the file list, place the mouse cursor over the scroll bar in the desired relative position and click the left button. The slider box and highlight bar will be repositioned accordingly. ALLY - A Lisp Analyzer 23 Version 2.0 User's Manual Press [Esc] to exit the file selection window. You can also exit by pressing [F10] or [Alt-X], pressing both mouse buttons simultaneously, or 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. ALLY - A Lisp Analyzer 24 Version 2.0 User's Manual 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. +--------------------------------------------/ | F1-Help F2-Opt F3-File F4-Check F5-Analyze +------------------------------------------/ ^F1 Kelv ^F2 Lb ^F3 Copy /------------------------------------+ F7-Browse F8-Edit F9-Shell F10-Exit | /--------------------------------------+ ^F4 Dir ^F5 Ljbook ^F6 Del 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 the previous section of the manual 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. ALLY - A Lisp Analyzer 25 Version 2.0 User's Manual 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 file errors - such as a nonexistent source 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. ALLY - A Lisp Analyzer 26 Version 2.0 User's Manual 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 an 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 many versions of DOS, this makes as much as 3.5 kilobytes more memory available for the program being executed. You can use ALLY's square bracket, semicolon, and asterisk filename alias symbols when entering your command line. See the preceding INSTALL USER PROGRAMS section for a description of the file name alias symbols. To maximize the amount of memory for the DOS shell, ALLY swaps most of its own code and data out of memory - into expanded memory if available, otherwise into a temporary hidden disk file (ALLY0000.$$$). See USING EXPANDED MEMORY for details. ALLY - A Lisp Analyzer 27 Version 2.0 User's Manual There is one warning we wish to stress. You may pop up a TSR (Terminate and Stay Resident) program which is already loaded, 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 the ALLY AutoCAD interface). 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 loaded 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. ALLY - A Lisp Analyzer 28 Version 2.0 User's Manual ------------------------------------------------------------ THE ALLY CHECKER ------------------------------------------------------------ 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 automatically wrapped and indented. A plus mark in the line number column indicates a wrapped line. 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. This makes quoted strings and comments stand out from the rest of the code. The change in color (or lack of change) makes it easy to recognize cases of missing quote marks and semicolons. 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 as ^H. See this manual's Appendix A for an ASCII table of control characters. The Checker's status/command line shows the number of parentheses which are open at the point following the last line of code displayed on screen. This number should always be zero when you reach the end of file. If a parentheses error is detected all following parentheses are displayed in blinking white. This does not necessarily pinpoint the error, but does show where it becomes apparent. Here are the command keys used within the ALLY Checker: [G] ........ Go to. Prompts for and moves to specified line. [A] or [Esc] Aborts browsing and returns the Workbench. [Up]/[Down] Cursor keys, moves display up or down one line. ALLY - A Lisp Analyzer 29 Version 2.0 User's Manual [Home] ..... Moves the display to the first line. [End] ...... Moves the display to the end of the file. [PgUp] ..... Displays the previous screen of code. [PgDn] ..... Displays the next screen of code. [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. ALLY - A Lisp Analyzer 30 Version 2.0 User's Manual ------------------------------------------------------------ THE ALLY ANALYZER ------------------------------------------------------------ A symbol cross-referencer and more, the ALLY Analyzer performs several functions to help debug and document your AutoLISP programs. The ALLY Analyzer generates a seven part comprehensive report of errors, warnings symbol usage, scope and function calls. As ALLY reads your AutoLISP files, it checks for and reports unbalanced parentheses, unclosed quotes, misused symbols, and other common errors. ALLY will generate a file hierarchy, a function call hierarchy, and separate cross- reference reports of user defined functions, user defined symbols, and AutoLISP's reserved subrs and symbols. A line-numbered program listing follows the cross-references. Several formatting options are offered. The size of files which ALLY can analyze is only limited by the amount of memory available. Several source code files may be analyzed at once. ALLY's read buffer can be adjusted to read lines up to 64K in length. The destination of ALLY's report is user selectable, offering a choice of output to screen, disk file, printer, text editor, or file browser. ALLY's built-in screen output is a simple mechanism which can scroll a line at a time, scroll a page at a time, or scroll nonstop. Nonstop scrolling can be halted by pressing any key. For more flexible screen output, install your favorite file browser and direct ALLY's output to it. ALLY displays a status window as the file is being analyzed. To abort the analysis, you can press the [Esc] key at any time, or press both mouse buttons simultaneously. ALLY - A Lisp Analyzer 31 Version 2.0 User's Manual 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(filename) Here are a couple of examples: ;ALLY(TrigFunc.lsp) - trigonometric routines. ;ally(D:\Lisp\MyFile.Lsp) Use the conventional DOS backslash for directory path separators, not AutoLISP's forward slash. 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. ALLY - A Lisp Analyzer 32 Version 2.0 User's Manual DECLARATIONS AND SYMBOL SCOPE ------------------------------------------------------------ The scope of a symbol is the region of the program 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 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 (if any) 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. ALLY - A Lisp Analyzer 33 Version 2.0 User's Manual There are two major methods employed for computer language scoping, dynamic (run-time) scoping and lexical (compile-time) scoping. AutoLISP's interpreter uses dynamic scoping, whereas most compiled LISPs and other languages use lexical scoping by default. Since AutoLISP's scoping is unlike the majority of 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. Functions Test, Check and Write are global (Check and Write are nested, but undeclared). Test's local symbol S is set to "two", and the global symbol S is set to "three". Test's function call to Check passes the value "one" to Check's argument S. (setq S "three") (defun Test ( / S) (defun Check (S) (Write) ) (defun Write () (print S) ) (setq S "two") (Check "one") (princ) ) Under AutoLISP's dynamic scoping, executing Test will print the word "one", whereas a lexical scoped LISP would print the word "two". 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 bindings. A dynamically scoped language searches for free variables, top down, in the call stack calling environments. The call stack is a record of active function calls. As each call is made, the called function's local environment record is placed on the top of the stack. Upon exit, the function's record is popped off the top of the stack. When one function calls another, the called function stacks on top of the calling function. The called function may in turn call another, and so on, further deepening the stack. Each called function has full access to the local symbol bindings of all other function environments below it in the stack. ALLY - A Lisp Analyzer 34 Version 2.0 User's Manual Where there are multiple local bindings of identically named symbols, the called function uses the first one encountered in its top down search. The global environment is searched only after exhausting the call stack without a match. In our dynamic example, the top down search 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 the next function - 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. Nesting is accomplished by physically placing function definitions inside one another in the source code. Lexical scoping does not require inner functions to be made local to outer functions in order to be considered nested. 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 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 - the global environment in this case. +---Write---+ +-------Global--------+ | S=? | | S="three" | | | | +-----Test------+ | +---Check---+ | | S="two" | | | S="one" | | | +--Check--+ | | | | | | | S="one" | | | +---Test----+ | | +---------+ | | | S="two" | | | | | | | | | +--Write--+ | | +--Global---+ | | | S=? | | | | S="three" | | | +---------+ | | | | | +---------------+ | +-----------+ +---------------------+ DYNAMIC SCOPE CALL STACK LEXICAL SCOPE NESTED ENVIRONMENTS (AUTOLISP) (OTHER LANGUAGES) ALLY - A Lisp Analyzer 35 Version 2.0 User's Manual 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 user defined functions will return a value, but consider those which need to set or 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. ALLY - A Lisp Analyzer 36 Version 2.0 User's Manual WARNINGS REPORTED ------------------------------------------------------------ ALLY performs error checking as it analyzes your AutoLISP source. One of the most common errors is missing or misplaced parentheses. ALLY reports all parentheses errors with the line where it became apparent. 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 will accept 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. 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 an 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. 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 - A Lisp Analyzer 37 Version 2.0 User's Manual 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. A sample report follows. When multiple files are analyzed, the file name heads each section. 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 show up as an undefined function. ALLY - A Lisp Analyzer 38 Version 2.0 User's Manual FILE HIERARCHY OF USER DEFINED FUNCTIONS ------------------------------------------------------------ The file hierarchy which ALLY generates is a tree structure of all user defined functions, including lambdas. This serves as a table of contents of your AutoLISP file. All globally accessible functions are shown as branches of the AutoLISP 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 a short example: File C:\ACAD\FILE1.LSP +--C:CMORE (1-107) | +--PRNT (4-18) | | +--lambda#01 (11-12) | +--lambda#02 (52-52) File C:\ACAD\FILE2.LSP +--DRWLIN (1-32) +--lambda#03 (17-18) Use this report to determine if a function is nested and to quickly locate its position in the file. ALLY - A Lisp Analyzer 39 Version 2.0 User's Manual 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 functions which call themselves are truncated at the first recursion and marked with three periods following the function name. Deep recursion, or circular calls with intervening functions are illustrated likewise. The following example illustrates a case where one function, DRWLIN, is being called at different levels, and another function, PRNT, recursively calls itself. global +--C:CMORE | +--DRWLIN | | +--lambda#03 | +--lambda#02 | +--PRNT | +--DRWLIN | | +--lambda#03 | +--lambda#01 | +--PRNT... +--C:XLINE +--RUBLIN +--lambda#04 To determine a function's hierarchy, follow its branch inward to the root. To determine its dependencies, follow its branches outward. ALLY - A Lisp Analyzer 40 Version 2.0 User's Manual 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. The scope of a function is determined by where and if it is declared (see the preceding DECLARATIONS AND SYMBOL SCOPE section for more details). A list of symbols declared by the function follows the usage report, and lastly, a list of symbols used directly by the function is shown. Keep in mind that some apparently unused symbols may have been declared for use as dynamic free variables in a called function. Take a look at the warnings report and the cross reference of the symbol in question to determine if it is truly extraneous. Here is a sample listing of an analysis of a single file. lambda#01 def in PRNT 11 PRNT dec in C:CMORE 1 def in C:CMORE 4 cal in C:CMORE 39,44 decs BSET uses a2 BSET pt1 i1 i2 xdata When multiple files are analyzed, the file name precedes the parent function names for each usage as in this example. DRWLIN undeclared (global) def in FILE2 (global) 1 cal in FILE1 PRNT 12 cal in FILE1 C:CMORE 89,92 decs ss1 uses ang1 pt1 pt2 ss1 ALLY - A Lisp Analyzer 41 Version 2.0 User's Manual 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). It is common to have duplicate symbol names, each declared within and belonging to different functions. Using dynamic scoping rules, ALLY properly treats these as separate and distinct symbols. A sample symbol listing follows. The format of the cross- reference is similar to the function report section. Note that two unrelated symbols share the name BSET, a perfectly acceptable practice. bset dec in C:CMORE 1 set in C:CMORE 89 ref in C:CMORE 99 bset dec in PRNT 4 set in PRNT 12 ref in PRNT 16 Like user defined functions, when multiple files are analyzed the file name precedes the parent function names of each symbol usage. edat dec in FILE1 C:CMORE 1 ref in FILE1 lambda#1 5 set in FILE1 C:CMORE 29,36,50,59,68,89,94 ref in FILE1 C:CMORE 31,32,36,54,55,56,71,72,90, 92,95 ref in FILE2 DRWLIN 12,17 ral dec in FILE2 DRWLIN 1 ref in FILE2 DRWLIN 8 ALLY - A Lisp Analyzer 42 Version 2.0 User's Manual 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 follows. 1+ cal in PRNT 18 cal in C:CMORE 42,43,89 cdr cal in lambda#1 5 cal in PRNT 6,13 cal in C:CMORE 29,31,36,54,55,65,68,71,72,79,90 ALLY - A Lisp Analyzer 43 Version 2.0 User's Manual 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 sample below. 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). ALLY - A Lisp Analyzer 44 Version 2.0 User's Manual 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 flexibility, send the report to your editor or browser instead. From Setup's Execution Options screen, you can configure ALLY to use 43-line EGA or 50-line VGA display 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. ALLY - A Lisp Analyzer 45 Version 2.0 User's Manual ------------------------------------------------------------ PROBLEMS AND ERROR MESSAGES ------------------------------------------------------------ Consult this section if you are having problems running ALLY. PROBLEMS WITH ACAD.LSP OR ACAD.PGP ------------------------------------------------------------ If you have just installed ALLY and find that entering ALLY at the AutoCAD command prompt yields no results, inspect your ACAD.LSP and ACAD.PGP files to insure ALLY was actually installed. A common problem is finding two ACAD.PGP or ACAD.LSP files existing in different directories on your system, with AutoCAD using the one without ALLY installed. Another common problem occurs when AutoCAD's ACAD environment variable is not set to the ALLY directory, and/or the ALLY! command in the ACAD.PGP file lacks a proper directory path to ALLYWB. The ALLY AutoLISP interface is so small, it is doubtful that you will ever experience a LISP related problem with it, but just in case, here are some of the things to look for. If you are using an older version of AutoCAD and see the message "Insufficient memory -- AutoLISP disabled" when you execute it, you probably have too many TSR (Terminate and stay resident) programs loaded. You will need to eliminate one or more of them if you wish to use AutoLISP programs. Should you see messages like "insufficient node space" or "insufficient string space" when trying to execute the ALLY AutoLISP interface, you have inadequate memory set aside for the LISP programs you have loaded. In most cases this can be corrected by either: 1) adding a (vmon) command to the top of your ACAD.LSP file, 2) reconfiguring your LISPHEAP and LISPSTACK variables, 3) using Extended AutoLISP (R10+ non-386 versions), or 4) hardware permitting, upgrading to AutoCAD 386. Refer to your AutoLISP Programmer's Reference and your AutoCAD Installation and Performance Guide for more information on memory management. If you have configured your ALLY installation to reset your digitizer/mouse driver after running ALLY, and the automatic LISP file loading routine fails, it could be one of two things. ALLY - A Lisp Analyzer 46 Version 2.0 User's Manual One, you have ALLYXM.SCR in a directory not pointed to by the ACAD environment variable (see INSTALLATION), or two, the ALLYXM.SCR file needs to be edited to match your AutoCAD plotter driver. If you have your AutoCAD plotter driver set to "None", there should be no spaces between the Ctrl-C character (ASCII 3, usually displayed as a heart) and the word ALLOAD in the second line of ALLYXM.SCR. With any other plotter driver, there must be one space between Ctrl-C and ALLOAD. PROBLEMS WITH ALLY EXECUTABLE FILES ------------------------------------------------------------ When you run ALLY from within AutoCAD, memory considerations sometimes cause problems. Insufficient memory problems can manifest themselves in several ways, but are usually easy to correct. There are two solutions we can take. One is to decrease ALLY's memory requirements by disabling features. The other - and more favorable - approach is to make more memory available to ALLY. The method you use may depend on the exact problem and the AutoCAD version used. If the ALLY LISP routine seems to function but the ALLY Workbench will not execute, you should first verify that your ACAD.PGP file includes the proper ALLY! command line as described in the Installation section. If you see the message "bad command or file name", it may be that you need to add a path to ALLYWB. If instead you see "EXEC failure", you need to increase the memory available to ALLY. The ALLY Analyzer or Checker may halt with an insufficient memory message when analyzing large or multiple files. Since the ALLY Analyzer allocates memory as needed, the larger the file, or the more files analyzed together, the more memory ALLY requires. To correct this, either decrease ALLY's memory requirements or make more memory available to ALLY. Another potential problem is your Workbench interfaced editor, browser or other external program not executing properly. Sometimes the only indication you may have of this is a flash as the screen clears and is redrawn. First, check the ALLY setup options to see that the program is properly installed with the correct path and name. If this checks, there is probably insufficient memory for the program, and you will need to either substitute a smaller program or make more memory available to ALLY. If your installation uses a non-386 version of AutoCAD, you can make more memory available to ALLY by increasing the memory reserve for the ALLY! command in your ACAD.PGP file. The INSTALLATION chapter of this manual explains how to change the memory reserve. ALLY - A Lisp Analyzer 47 Version 2.0 User's Manual In AutoCAD 386 installations using the Phar Lap DOS Extender, you always get the maximum amount of memory for external programs regardless of the number you place in the memory reserve field. Memory managers and DOS 5.0 can increase the amount of base memory available. Unfortunately, there is about 200K which earlier versions of the DOS Extender does not release. There are at least two commercial applications designed to recover memory from the DOS Extender, and one from Autodesk called SHROOM which is shipped with AutoCAD 386 R11 (a shareware version of SHROOM is available in the CompuServe ADESK forum). As an alternate or additional method of increasing the memory released by the DOS Extender, Autodesk has a program called NEWDX (also available on CompuServe) which upgrades the Phar Lap DOS Extender to a later version with a smaller kernel. To lessen ALLY's memory requirements, you can disable the Call Hierarchy, disable the X-ref Reserved option, and/or reduce the Read Buffer size. You rarely need to cross-reference reserved symbols, but the Call Hierarchy is generally too useful to consider disabling. A large Read Buffer lessens the memory available for symbol storage and 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. Lessening ALLY's memory requirements may not be enough - the best solution is to increase the amount of memory available to ALLY using one of the methods described earlier. Remember, if these attempts to increase the available memory fail or fall short, you still have the option of running ALLY directly from DOS. ALLY - A Lisp Analyzer 48 Version 2.0 User's Manual ------------------------------------------------------------ APPENDIX A - ASCII TABLE ------------------------------------------------------------ +----------------+-----------+-----------+-----------+ | 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 | +----------------+-----------+-----------+-----------+ ALLY - A Lisp Analyzer 49 Version 2.0 User's Manual ------------------------------------------------------------ APPENDIX B - PRINTER COMMANDS ------------------------------------------------------------ The following is a table of printer control codes and escape sequences used by IBM and Epson nine-wire dot-matrix printers, and compatibles such as Panasonic. This is not a full command listing, just a few you might find useful to execute before and after printing the ALLY Analyzer's report. Use decimal ASCII codes as shown below for ALLY's printer setup and reset strings. To send multiple commands in the strings, simply chain them together, separating them with commas. For example, to turn skip-perforation off, set compressed mode and set 1/8 inch line spacing you would use the following string: 27,79,15,27,48 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 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. Consult your printer manual for more details and commands specific to your hardware. The ASCII table in Appendix A will help you translate other commands into the decimal ASCII strings required by ALLY. ------------------------------------------------------------ Code or Decimal Printer Sequence ASCII Function ------------------------------------------------------------ FF 12 Form feed (to next top of form) 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 ALLY - A Lisp Analyzer 50 Version 2.0 User's Manual ------------------------------------------------------------ Code or Decimal Printer Sequence ASCII Function ------------------------------------------------------------ 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] ALLY - A Lisp Analyzer 51 Version 2.0 User's Manual ------------------------------------------------------------ INDEX ------------------------------------------------------------ Abort .................................... 8, 26, 29, 31, 45 ACAD.LSP .......................................... 4, 5, 46 ACAD.PGP ....................................... 4-6, 46, 47 ACADLIMEM ................................................ 5 ALLY.BAT ................................................. 4 ALLY.LSP .............................................. 4, 5 Alias (filename) ................................ 12, 26, 27 ALLYAN.EXE ............................................... 4 ALLYCK.EXE ............................................... 4 ALLYSU.EXE ............................................... 4 ALLYWB.EXE ............................................... 4 ALLYXM.SCR ........................................... 4, 47 Ampersand ........................................... 11, 27 Analyze [F5] or [Alt-A] command ..................... 26, 31 Analyzer ................ 13, 15, 17, 19, 21, 26, 31, 45, 47 Appendixes .......................................... 49, 50 Arguments ........................................... 33, 36 ASCII ............................ 12, 16, 19, 20, 29, 49-50 ASCII lines ............................................. 16 Asterisk ............................................ 12, 27 AutoCAD ................................. 4-6, 21, 28, 46-48 AutoCAD 386 ................................... 5, 6, 46, 48 AUTOEXEC.BAT ......................................... 5, 11 AutoLISP .. 3, 12, 15, 16, 21, 22, 26, 31, 33-39, 43, 44, 46 Bottom margin ........................................... 14 Browse [F7] or [Alt-B] command ...................... 11, 26 Browser ............................. 11, 17, 22, 26, 29, 45 Call, Called ................. 15, 33-35, 37, 40, 41, 43, 48 CFIG386.EXE .............................................. 5 CFIGPHAR.EXE ............................................. 5 Check [F4] or [Alt-C] command ....................... 25, 29 Checker ..................................... 17, 18, 25, 29 Control-End, Control-Home ................................ 8 Control-Left, Control-Right .............................. 7 Cross-reference .......................... 15, 31, 41-43, 48 Data entry editing keys ................................ 7-9 Declaration .......................................... 33-36 Define Page ......................................... 10, 13 Destination ................................. 21, 22, 24, 31 Directory .................. 4, 5, 11, 21-24, 27, 32, 46, 47 Disk, Disk drive ............................. 4, 12, 24, 27 Double space ............................................ 16 Dynamic scoping, variables ................... 15, 33-36, 40 Edit [F8] or [Alt-E] command ........................ 11, 26 Editor .................... 3, 4, 11, 12, 18, 21, 22, 26, 47 Errors ...................................... 29, 31, 37, 38 Execution Options ................................... 10, 17 Exit [F10] or [Alt-X] command ..................... 7, 9, 28 Expanded memory, EMS ............................. 5, 12, 27 ALLY - A Lisp Analyzer 52 Version 2.0 User's Manual External programs ................... 11, 21, 25, 28, 47, 48 File [F3] or [Alt-F] command ........................ 23, 25 File/Destination ........................................ 21 File directory ....................................... 21-24 File search mask ........................................ 21 File selection .......................................... 23 File sort method .................................... 17, 23 Form feeds .............................................. 16 Function call ............................... 33, 34, 36, 40 Function keys ........................................... 25 Global symbols ............................... 33-36, 40, 41 Help [F1] or [Alt-H] command ............................ 25 Hierarchy ................................... 15, 39, 40, 48 Hot spots ............................................ 9, 23 Installation ............................................. 4 Left bracket ........................................ 12, 27 Left margin ............................................. 13 Lisp file name ....................................... 22-24 LISPHEAP ................................................ 46 LISPSTACK ............................................... 46 MAXVCPI switch ........................................... 5 Memory ............................. 5, 6, 33, 36, 37, 46-48 Mono colors ............................................. 18 Mouse ............................. 8, 9, 18, 23, 30, 45, 46 Multiple files ...................... 28, 32, 39, 41, 42, 47 Nested functions ................................ 33, 35, 39 Opt(tions) [F2] or [Alt-O] command .................. 10, 25 Page breaks ............................................. 16 Page length ......................................... 13, 14 Page width .......................................... 13, 44 Parameters .................................. 11, 26, 27, 36 Parentheses, Parentheses errors ............. 18, 29, 31, 37 Path .................. 4, 5, 11, 12, 21, 22, 27, 32, 46, 47 Peek [F3] or [Alt-P] command ............................ 24 Phar Lap DOS Extender ................................... 48 Printer ......................... 13, 16, 19, 20, 22, 50, 51 Printer Options ..................................... 10, 19 Printer port ............................................ 19 Printer reset ....................................... 19, 20 Printer setup ............................... 10, 19, 20, 50 Problems ..................................... 6, 37, 46, 47 Program listing ..................................... 16, 44 Protected AutoLISP files ............................. 5, 26 Question mark ................................... 11, 12, 27 Quote errors ........................................ 29, 37 Report ....................... 12, 15, 21, 22, 24, 26, 31-44 Report directory ........................................ 22 Report file name .................................... 12, 22 Report options ...................................... 10, 15 Reserved LISP subrs and symbols ......... 15, 33, 37, 43, 48 Right bracket ....................................... 12, 27 Right margin ............................................ 13 ALLY - A Lisp Analyzer 53 Version 2.0 User's Manual Scope ............................. 15, 31, 33-36, 38, 40-42 Scroll bar ........................................... 9, 23 Setup options ....................................... 10, 25 Shell [F9] or [Alt-S] command ........................... 27 SHROOM program .......................................... 48 Slider box ........................................... 9, 23 Sort [F9] or [Alt-S] command ............................ 23 Sorting files ....................................... 17, 23 Subdirectories ...................................... 23, 24 Swap, Swap file .................................. 5, 12, 27 Symbols ...................... 12, 15, 27, 31, 33-36, 42, 43 Tab characters .................................. 17, 29, 44 Top margin .............................................. 14 TSR ............................................. 12, 28, 46 Unprintable characters .................................. 44 User defined functions .............................. 39, 41 User defined symbols .................................... 42 Warnings ................................................ 37 Workbench ............................................ 21-28 Workbench commands ...................................... 25 X-ref reserved .................................. 15, 43, 48 ALLY - A Lisp Analyzer 54 Version 2.0 User's Manual