MicroSurvey CAD Lisp Programming Functions

The LISP programming extensions are a set of LISP routines designed to help you customize MicroSurvey CAD or inCAD to your needs. The LISP extensions allow you to use the information in the MicroSurvey database to extend MicroSurvey in any direction you choose.  Note that most of these functions work equally well in both MicroSurvey CAD and MicroSurvey inCAD.  In this document, we refer to MicroSurvey.

Many of the functions provided here are the same C language routines MicroSurvey uses internally, with the LISP interface simply allowing you to call them directly. We cannot predict the types of programs you will write using MicroSurvey programming extensions, but these functions should provide a firm foundation for your efforts. The MicroSurvey database is open and at your disposal. What other Surveying Software company provides you with this kind of power?

LISP routines can be activated two ways with MicroSurvey CAD:

1. You can open Tools | Load Application, Pick "Add File... , select "Lisp Application" from the "Files of type" pulldown and then navigate to the location you have stored the lisp file.  See  the IntelliCAD Help article on the APPLOAD function for further details.  After that you can activate the routine by typing the command in the command line.

2. If you need to use the lisp routine on a regular basis, follow these steps after you've tested the routine and are confident it will work properly:

i. ensure you are logged in as an administrator and that MicroSurvey CAD is closed

ii. Copy the lisp file(s) into:

Windows XP: C:\Documents and Settings\All Users\Application Data\MicroSurvey\MSCAD\yyyy\mscad

Windows Vista,7,8 or newer: C:\ProgramData\MicroSurvey\MSCAD\yyyy\mscad

iii. Open this file in Windows Notepad:

64 bit systems: C:\Program Files\MicroSurvey\MSCADyyyy\icad.lsp

32 bit systems: C:\Program Files (x86)\MicroSurvey\MSCADyyyy\icad.lsp

iv. Add an additional line to the file for each lisp routine you wish to have loaded when the program starts in the format:

(load "mylisproutine")

For example:

(load "qsopts")

(load "origin")

(load "rorigin")

(load "mylisproutine")

;(load "tablet/tablet") 

v. (IMPORTANT) When you're finished editing icad.lsp you must first save it to the desktop and then copy it back to its original location to overwrite the original; otherwise it won't update properly.  Windows Vista and newer operating systems will not allow you to save the file directly into the Program file folder without special arrangements.

vi. Run MicroSurveyCAD.  You can type the command for the lisp routine in the command line to activate it, or you can add the command to a customized menu or toolbar.

Please note that the MicroSurvey lisp programming extensions currently only support numeric point numbers; alphanumeric point names cannot be used.

Toggle Control Functions
Drawing Control Functions
Unit Functions
Coordinate Database Functions
Line Database Functions
Annotation Functions

MicroSurvey Toggle Control Functions

The MicroSurvey Toggle Control Functions control the settings of the System Toggles. All these functions work the same way. Passing a value to a function will cause that value to be set in its associated toggle; calling a function without passing a value will return the existing setting.

To use one of these functions, evaluate the LISP expression

(function_name [bool])

where

• function_name is the name of the function
• bool is an optional Boolean value, 1 or nil

The expression evaluates to the final value of the toggle. Examples:

To set the Input Scale Factor toggle ON:

(setq togval (in_scale_tog 1))

To set the same toggle OFF:

(setq togval (in_scale_tog nil))

To return the current setting:

(setq togval (in_scale_tog))

MicroSurvey Drawing Control Functions

The MicroSurvey Drawing Control Functions control the settings of the MicroSurvey Drawing Control Toggles described in the manual. These functions work just like the MicroSurvey Control Functions described above; you set a toggle by passing a Boolean value to the function, or pass no value to return the existing setting.

Examples:

To set the Draw Lines toggle ON:

(setq togval (drawlines_tog 1))

To set the same toggle OFF:

(setq togval (drawlines_tog nil))

To return the current setting:

(setq togval (drawlines_tog))

MicroSurvey Unit Functions

The MicroSurvey Unit Functions return the values of MicroSurvey system variables. To use a function, evaluate the LISP expression

(function_name)

where function_name is the name of the function. For example, to read the drawing scale factor, use:

(setq scale (get_scale_factor))

To set the scale factor use set_scale_factor.

(set_scale_factor 100.0) would set the scale to 1"=100' if the units are feet, or 1:100 if the units are metric.

MicroSurvey Coordinate Database Functions

The MicroSurvey Coordinate Database Functions manipulate coordinate points in the database. All these functions return nil if an error occurs. Descriptions of these functions follow.

get_coordinate

The function get_coordinate returns the information stored with a point in the coordinate database.

Syntax: (get_coordinate pointnum)

Integer: pointnum

Return Value: Returns a list:

("number" (east north elev) desc)

where

• number is a string variable; you can convert this to a number with (itoa)
• (east north elev) is a list of real numbers in MicroSurvey Point variable format
• desc is a string variable of up to 50 characters

Example 1:

(setq ptnum (getint "\nEnter the Point number:"))

(setq ptlist (get_coordinate ptnum))

This sequence will accept a point number from the operator and return the point data in ptlist. To get each item of information into a variable, use the following:

(if (/= nil ptlist) ; check to make sure it came back
(setq ptnum (itoa (car ptlist)))
(setq ptxyz (cadr ptlist)) ; the point itself
(setq x (car ptxyz))
(setq y (cadr ptxyz))
(setq z (caddr ptxyz))
(setq ptdesc(caddr ptlist))

Example 2: This program will draw lines by point numbers:

 (defun drawlines()
   (while
      (setq‚  pt1xyz (cadr (get_coordinate (getint "\nEnter the first Point number:"))))
      (setq pt2xyz (cadr (get_coordinate‚  (getint "\nEnter the second Point number:"))))
      (command "line" pt1xyz pt2xyz "")
   )
)

store_coordinate 

The function store_coordinate stores a point in the coordinate database, with full Point Protection. If the Point Protection toggle is ON, you will be prompted with the standard options if you attempt to overwrite a point.

Syntax: (store_coordinate "number" (east north elev) ["description"])

Where:

• number is a string variable; you can convert a number to a string with (itoa)
• (east north elev) is a list of real numbers in MicroSurvey Point variable format
• description is an optional string variable of up to 50 characters

Return Value: Returns a list:

("number" (east north elev) desc)

where

• number is a string variable; you can convert this to a number with (itoa)
• (east north elev) is a list of real numbers in MicroSurvey Point variable format
• desc is a string variable of up to 50 characters

It is important to examine the returned list, because Point Protection can affect the values. If you choose New or Unused in response to a Point Protection prompt, the returned point number will be changed.

Example:

 (setq pt (getpoint "\nPick a Point:"))
 (setq number (getstring "\nEnter the Point number:"))
 (setq desc (getstring "\nEnter the description:"))
 (setq ptreturned (store_coordinate‚ ‚  number pt desc))
 (if (/=‚  (atoi (car ptreturned))‚  (atoi number))
  (princ‚  "\nDifferent number returned!")
 )

delete_coordinate 

The function delete_coordinate deletes a coordinate from the MicroSurvey coordinate database. If you erase a point, all lines, bearings, distances, elevations, descriptions, and point numbers related to that point will disappear from the screen and the MicroSurvey drawing file.

Syntax: (delete_coordinate num)

where num is an integer

Return Value: returns the string "Ok" if successful.

returns nil if the point does not exist

Example:

(setq ptnum (getint "\nEnter the Point number to delete:"))
(if (/= nil ptnum) 
  (delete_coordinate ptnum)
)

find_coordinate 

The function find_coordinate finds all points within a specified search radius of a given CAD point (not necessarily a MicroSurvey point). It can be used in a stake out program, or a program for automatic connectivity.

Syntax: (find_coordinate (east north elev) distance)

where

• east north elev is an CAD Point variable (X Y Z)
• distance is a real number search radius

Return Value: Returns a list:

("num1" "num2" ...)

where

• num1, num2... are string variables containing the point numbers of the points found within the search radius

Example:

 (setq radius (getreal "\nEnter the search radius:"))
 (setq searchpoint (getpoint "\nPick the Point to search around:"))
 (setq pointlist (find_coordinate‚  searchpoint radius)
 (princ pointlist)

get_highest 

The function get_highest finds the highest used point number in the database. This is useful if you wish to write a program that will add coordinates to the database.

Syntax: (get_highest)

Return Value: Returns a string:

("num1")

get_lowest_available 

The function get_lowest_available finds the lowest unused point number in the database. This is useful if you wish to write a program that will add coordinates to the database. Syntax is idential to (get_highest)

find_coordinate_description

The function find_coordinate_description finds all the points with this description:

Syntax: (find_coordinate_desc "POST")

Return Value: Returns a list:

"1174" "1223"

get_descriptions 

The function get_descriptions returns a list of all the descriptions used in the coordinate file.

Syntax: (get_descriptions)

Return Value: Returns a list:

"TREE" "POST" "HYDRO POLE" "BAR"

MicroSurvey Line Database Functions

The MicroSurvey Line Database Functions manipulate lines in the line database. All these functions return nil if an error occurs. Descriptions of these functions follow.

add_line 

The function add_line adds a line to the line database. The presence of this line allows MicroSurvey to automatically recalculate bearings and distances if a point at either end of the line moves.

Syntax: (add_line start_num end_num [center_num])

where

• start_num, end_num are required integers representing point numbers at the start and end of the line
• center_num is an optional integer representing a radial point number for a curve

Return Value: Returns a string "line_hndl"

where 

• line_hndl is a string variable containing the CAD handle of the line. The handle is a hexadecimal number that is converted to a long integer and becomes an index into the MicroSurvey line database. This value is returned for your information only.

Example: 

(setq pt1num (getint "\nEnter first Point number:"))

(setq pt2num (getint "\nEnter second Point number:"))

(setq linehandle‚  (add_line pt1num pt2num))

get_line 

The function get_line returns the CAD handle of a MicroSurvey line that connects two points.

Syntax: (get_line start_num end_num [center_num])

where

• start_num, end_num are required integers representing point numbers at the start and end of the line
• center_num is an optional integer representing a radial point number for a curve

Return Value: Returns a string "line_hndl"

where

• line_hndl is the string handle of the line connecting the two points. The handle is a hexadecimal number.

Returns nil if there is no MicroSurvey line connecting the points.

Example:

(setq pt1num (getint "\nEnter first Point number:"))

(setq pt2num (getint "\nEnter second Point number:"))

(setq linehandle (get_line pt1num pt2num))

find_line 

The function find_line finds all points that are connected to a given point by lines and curves. It is useful, for example, in finding what points are connected to a lot corner.

Syntax: (find_line num)

where num is an integer point number

Return Value: Returns a list:

("line_hndl1" "line_hndl2" ...)

where

"line_hndl1", "line_hndl2"... are CAD string handles to the lines.

Example:

(setq pt1 (getint "\nEnter the Point number to search for connections:"))
(setq pointlist‚ (find_line‚  pt1))
(if (/= nil pointlist)
  (princ (strcat "\nSome lines were found connecting to Point:"‚  (itoa‚  pt1)))
)
                ‚ 

get_line_data 

The function get_line_data returns all the information stored in connection with a line. This information could be used to move points, or erase bearings or distances.

Syntax: (get_line_data "line_hndl")

where 

line_hndl is a string variable of the form returned from find_line above.

Return Value: Returns a list:

(line_hndl start_num end_num center_num bear_hndl dist_hndl)

where

• line_hndl should be the same string variable passed as a parameter to get_line_data
• start_num and end_num are point number strings. These can be converted to integers with (atoi)
• center_num is a point number string representing a radial point if this is a curve
• bear_hndl and dist_hndl are string handles of the bearing and distance annotations on the line, if the line has been annotated. They are 0 if the line has not had a bearing or distance added to it.

Example:

(setq handlelist (find_line 1)) 

;finds the line handles connected to point number 1

(setq linedata (get_line (car handlelist))

delete_line 

The function delete_line removes a line from the line database. All related information (bearings and distances) will be removed automatically.

Syntax: (delete_line "line_hndl")

where

line_hndl is a string variable containing a hexadecimal CAD handle for the line.

Return Value: Returns "Ok" if successful and nil if unsuccessful

Example:

(setq list (find_line 3))
  (if (/= nil list)
  (delete_line (car list))
)

This sequence will delete any existing lines that connect to point 3.

MicroSurvey Annotation Functions

The MicroSurvey Annotation Functions add bearings and distances to lines in your drawing. Descriptions of these functions follow.

auto_bearing 

The function auto_bearing adds a bearing to a line. This is the routine used by the Auto Bearing function in MicroSurvey, but calling it from LISP lets you use it on any CAD line whether it was generated by MicroSurvey or not.

Syntax: (auto_bearing "line_hndl")

where

line_hndl is a string variable containing a hexadecimal CAD handle for the line.

A large arrow will appear on the line in question, and you will be asked what side of the line you want the bearing placed.

Return Value: Returns "Ok" if successful, and nil otherwise

Example:

(setq linehndl (find_line 3))

(auto_bearing linehndl)

auto_distance 

The function auto_distance adds a distance to a line. This is the routine used by the Auto Distance function in MicroSurvey, but calling it from LISP lets you use it on any CAD line whether it was generated by MicroSurvey or not.

Syntax: (auto_distance "line_hndl")

where

line_hndl is a string variable containing a hexadecimal CAD handle for the line.

A large arrow will appear on the line in question, and you will be asked what side of the line you want the distance placed.

Return Value: Returns "Ok" if successful, and nil otherwise

Example:

(setq linehndl (find_line 3))

(auto_distance linehndl)

auto_beardist

The function auto_beardist adds a bearing and a distance to a line. This is the routine used by the Auto Bear/Dist function in MicroSurvey, but calling it from LISP lets you use it on any line whether it was generated by MicroSurvey or not.

Syntax: (auto_beardist "line_hndl")

where

line_hndl is a string variable containing a CAD hexadecimal handle.

A large arrow will appear on the line in question, and you will be asked what side of the line you want the bearing placed.

Return Value Returns "Ok" if successful, or nil otherwise.

Created on: May 25, 2003
Updated: January 5, 2010 to fix some formatting problems