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)