std-var-push, std-var-pop


Synopsis

(std-var-push <alst>) ; sets new error stack frame

(std-var-pop) ; deletes last error stack frame

Description

These two functions deal with Error Stack Frames.

Error stack frames are used to save and restore a system state on normal function exit or abnormal exits: errors. This function pair is normally not used by the user, they are the workhorse for STD-VAR-INIT and STD-VAR-RESTORE. A stack frame consists of pairs, where the car is a keyword to denote the type to be restored and the cdr the actual data to be restored. If the keyword is a string it is the name of an AutoCAD system variable. Special save/restore pairs exist to handle AutoCAD table states. Our choosen name "error stack frame" might be misleading, most of the work is done without any error, saving the system state before and restoring the state afterwards, but the most important part happens on errors.

The actual error stack frame is stored in the global variable *STD:VAR-STACK*.

It stores internally all old settings to set them back on errors, break or STD-VAR-RESTORE at the end of the function.

The argument alist is a list of key value pairs. The keys are either strings or symbols.

Each string must be a valid and writable systemvariable. This is very important!. Otherwise in case of any error an "error inside error" will occur and the system will be left in an undefined state.

Each symbol marks a special feature. In general functions the pair STD-SAVE-<symbol-name> and STD-RESTORE-<symbol-name> are called to save and restore system settings.

The colon in the keywords is not needed and not used for looking up the function name of the save/restore function. For example the key :VPORTS calls STD-SAVE-VPORTS on STD-VAR-PUSH and STD-RESTORE-VPORTS on STD-VAR-POP.

You may easily define your own save/restore pairs to be able to extend the functionality of error handling.

See STDTBL for some predefined save/restore pairs.

Special predefined symbols are: #- SMALL

(:TRANSPARENT)

(:ERROR error-func)

(:FUNCTION old-func new-func)

(:FILE file)

;;; Entities, Graphics: (ignored by std-%var-simple-init)

(:ENTUPD ele*)

(:ENTDEL ele)

(:REDRAW [ele])

(:GRVECS [vecs])

;;; Tables: (ignored by std-%var-simple-init)

(:LAYER [laynam]), see STDTBL

(:UCS [ucs]), see STDTBL

(:ZOOM [p1 p2])

(:VIEW [view-name])

(:VPORTS [vports-name])

(:UNDO [undoctl])

These symbols are prefixed with a colon (":") and are keywords, symbols evaluating to themselves, which means that they don't have to be quoted.

Note

With the SMALL package those predefined symbols above are no keywords.

So you have to explicitly quote them, otherwise they will evaluate to nil.

The values have special meanings according the above table. They are special initialization parameters dependent on the key. They are usually parameters for the accompanied STD-SAVE- function.

STD-VAR-PUSH and STD-VAR-POP may be nested to any level, but STD-VAR-RESTORE pops all active stack frames. Nested STD-VAR-RESTORE calls may lead to "Tried to restore wrong error handler. Fixed." warnings. This should be avoided.

Special Predefined Error Stack Frame Keys

(:TRANSPARENT)

This is only used by std-var-init of recursive or transparently callable functions, such as a lisp function which is called by inside a input function (REF for reference points or MID a midpoint of two to be picked points) and requires a seperate error stack frame.

STD-VAR-INIT doesn't supply the default error handler and does UNDO GROUP, STD-VAR-RESTORE doesn't close files, delete temporare files and doesn't do UNDO END.

No action is done at initialization nor restauration, it is only a marker.

Note: In the current implementation there may still be problems with nested :TRANSPARENT calls of std-var-init and *error* functions.

(:ERROR . *std-error*)

This is used to set a special error handler function, other than *STD-ERROR* or *STD-SIMPLE-ERROR*. Normally it is not required to define your own error handler because error handling is extendable by calling any save/restore pairs.

The cdr must be the name of an error function (taking one argument) or a quoted lambda expression.

However if you define your own error handler be sure to supply one string argument, the error message, and call STD-VAR-RESTORE to reset the stack frame. It is very important to supply a correct error function! An unsafe error restauration may cause an unrecoverable "error inside "error*" and leaves your system in limbo.

The action is performed at initialization and restauration. See the more general :FUNCTION key below which may also be used instead. The error key has a special error frame pair.

(:FUNCTION old-func new-func)

This is seldom used to overload intermediatly a function by another with the same number and type of argumenrts. Examples are in STD-TIME, where File IO functions are overloaded to count the bytes read or written.

The action is performed at initialization and restauration.

(:FILE . file)

This is often used to close a file in case of errors or user breaks. The file value must be an open file. Normally files are closed automatically by using std-fopen and the global *FOPEN* list. But you may not want to use an explicit STD-FCLOSE, wait for an error or for STD-VAR-RESTORE that the file is closed. so you may use seperate open file stack frame, such as the with-open-file construct in common lisp.

The action (close the file) is performed at restauration only.

A usage example is in test/RUNTEST.LSP

(:ENTUPD . ele*)

The value may be a list of AutoCAD elements or just a single element.

In the restore case it regenerates all elements. This is useful for dealing with complex objects which are to be updated later for performance reasons. (blocks with a lot of attributes, polylines). On errors or breaks those objects have to be regenerated to reflect the changes made to so far.

The action is performed safely at restauration only.

(:ENTDEL . ele)

This takes a single AutoCAD element and flips the state of entity deletion, deleted or not.

The action (ENTDEL ele) is performed at restauration only.

(:REDRAW . [ele])

This takes a single AutoCAD element and flips the state of entity highlighting, highlighting on at initialization and off at restauration.

If no argument is provided, it performs a (redraw) at init and at restore time.

(:GRVECS . [vecs])

This takes an optional list of grvecs vectors (an edge list) redraws/clears the vectors at restauration with GRVECS. This is useful for cleaning xor'ed temporary graphics.

(:LAYER . [layer-name])

It saves the layer-state of the given layer and restores it on restauration. The layer may exist or not exist and created in between std-var-push and std-var-pop. After std-var-pop the state for this layer is the same as before.

If no layer-name value is provided, it does the same as with ("CLAYER"); it saves and restores the current layer only, but doesn't save any state (on/off, freeze/thaw, ...) of any layer.

See STD-SAVE-LAYER

(:UCS . [ucs])

This is normally called without the UCS value. It saves then the current UCS and restores it on restauration. If a value is given (a list according the specification in STD-RESTORE-UCS) this UCS is set. Normally it's easier to set an UCS with command or the VLA method. See STD-SAVE-UCS

(:ZOOM [p1 p2])

This safes and restores a zoom window only. With no value is stores the actual zoom extends (lower left and upper right corner of the current viewport). With a value provided (a list of two points) it performs a zoom window. See STD-SAVE-ZOOM

(:VIEW . [view-name])

This safes and restores an AutoCAD view which holds more information than the :ZOOM key. With no value is stores the actual VIEW. With value it sets the named view which must exist. See STD-SAVE-VIEW

(:VPORTS . [vports-name])

This safes and restores an AutoCAD viewport setting, the state of views subdivisions. With no value is stores the actual VPORT. With value it sets the named VPORT which must exist. See STD-SAVE-VPORTS

(:UNDO . [undoctl])

This safes and restores an AutoCAD UNDOCTL setting, the state of the UNDO handler. With no value is stores the actual UNDO setting. With a value it sets the UNDOCTL number as if UNDOCTL would be a writable systemvariable.

This is useful to turn off UNDO on very costly operations which would overflow the UNDO buffer. However you must know that disabling UNDO is dangerous!

It is used so far in test environments only, when thousands of unimportant test entities are created. See STD-SAVE-UNDO

This might be renamed to :UNDOCTL later but not to "UNDOCTL".

Arguments

alst: list of special key value pairs, a dotted pair list

Return Value

undefined

Side Effects

These functions are only called because of its side-effects. They set and restore various system settings, dependent on the argument alist. See the description above.

It stores and deletes one level of the intermediate stack frame in the global variable *STD:VAR-STACK*, a list of all active stack frames.

Module

(std-require 'STDERROR)

Defined in STDERROR