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?

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 Toggle Control Functions:

 

Function Name

Toggle Controlled

in_scale_tog

Input Scale Factor

out_scale_tog

Output Scale Factor

ss_trav_tog

Side Shot/Traverse Mode

auto_num_tog

Auto Numbering Toggle

auto_coord_tog

Auto Coordinate Toggle

desc_tog

Descriptions Toggle

offset_tog

Offsets Toggle

pt_protect_tog

Point Protection Toggle

elev_tog

Elevations Toggle

desc_trans_tog

Descriptions Translations Toggle

vert_ang_tog

Vertical Angle in COGO Toggle

meas_tog

Hz Angle & Hz Distance Prompt Toggle


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 Drawing Control Toggles

 

Function Name

Toggle Controlled

drawlines_tog

Add Lines in COGO Toggle

drawbearing_tog

Add Bearings in COGO Toggle

drawdistance_tog

Add Distances in COGO Toggle

drawelev_tog

Add Elevation text to screen Toggle

drawnum_tog

Add Point Number text to screen Toggle

drawpoint_tog

Add Point entity to screen Toggle

drawblock_tog

Add Custom CAD Blocks Toggle


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 Unit Functions

Function Name

get_scale_factor

set_scale_factor

get_elevation_decimal_places

get_distance_decimal_places

get_slope_decimal_places

set_slope_decimal_places

get_stationing_decimal_places

set_stationing_decimal_places

get_coordinate_decimal_places

set_coordinate_decimal_places

get_Metric_Imperial


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 Coordinate Database Functions

 

Function Name

Toggle Controlled

get_coordinate

Get a Coordinate

store_coordinate

Store N,E,Elev,Description for a point

delete_coordinate

Erase N,E,Elev,Description

find_coordinate

Finds nearest coordinate within radius

find_coordinate_desc

Returns a list of all points with this description

get_highest

Returns the highest database coordinate

get_lowest_available

Returns the first available coordinate number

get_descriptions

Returns a list of all the descriptions in the file


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 Line Database Functions

 

Function Name

Toggle Controlled

add_line

Adds line connectivity between points

get_line

Find CAD handle of a line

find_line

Finds all lines connected to a point

get_line_data

Get all information known about a line

delete_line

Remove a line from the database


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.

Example:

(setq linehndl (find_line 3))
(auto_beardist linehndl)