Home > User Guide > Model Management > History and Roll

Using History and Roll in Scheme

History and roll functionality is supported by Scheme AIDE, which can be used to rapidly test changes between states of an ACIS model. The default settings for history and roll in Scheme AIDE can be obtained through the option:list extension.

A decision about the history management type has to be made before modeling begins when a new part is created. With the exception of logging, none of the history stream options are designed to be changed during actual model creation.

Options for History Management

The options that are important for history streams are:

history_checks
When TRUE (default), additional checks are done on the integrity of the history stream data structure. When FALSE, no checks are done.
logging
When TRUE (default), bulletin boards and delta states are visible at the application level (it logs a change to the history stream). The bulletin boards are not deleted when the next one is open; they remain available. When FALSE, each bulletin board is deleted as soon as the next is opened (logging to the history stream is turned off). This is the one option:set parameter that can be changed after a model has been created.

Scheme Extensions for History Management

Use the following Scheme extensions to manage multiple history streams when working with multiple parts.

Part histories contain roll back information for all entities in a part. Obtain this history with (history part).

history
Gets a history stream from a part or ID or string
roll:delete-all-states
Deletes all delta states

The default history contains history for entities without history and in a part without part history. When distributed history is off (FALSE), the default history contains all history. When distributed history is on (TRUE), the default history contains history for entities that could not be found in a part. Obtain the default history with (history "default").

Start with a part:new

The first step in establishing a history stream is to create a new part, using the part:new extension.

The part:new extension takes an optional argument, size, which must be a prime number. It specifies how large to make the table that stores the entities in the part. This number does not limit the maximum number of entities that can be stored. However, if a part has many more entities than this number, performance slows whenever your application has to look up the entities in Scheme. If the number is much larger than the number of entities referenced from Scheme, then more memory is used than is actually needed. The default size is DEFAULT_PART_SIZE, which is defined in the file pmhusk/part_utl.hxx (value is 1009).

; part:new
; Define a new part
(define my_part (part:new))
;; my_part
; Define a new view for the part
(define my_view (view:dl my_part))
;; my_view

Turn on History and Roll

When the default settings are used:

Once the new part has been created, some of its history stream settings can be changed using the option:set extension.

For the settings to become active, the options must be changed in a new part before any model geometry has been created.

Use Distributed History Streams

Distributed history enables part history. After distribution is set (either on or off) it cannot be changed. Distributed history is off by default, and the first bulletin created in for a part's history stream locks it this state.

; part:new
; Define a new part
(define my_part (part:new))
;; my_part
; Define a new view for the part
(define my_view (view:dl my_part))
;; my_view
(env:set-active-part my_part)
;; ()
(part:set-distribution-mode #t)
;; #t

To use distributed history after it is enabled, create model geometry. At some point in the modeling, name it using roll:name-state. From that state, you can roll to some previous state using roll. Any new modeling operations performed from this state on are created in a new branch.

; roll:name-state
; Define a new part
(define my_part (part:new))
;; my_part
; Define a new view for the part
(define my_view (view:dl my_part))
;; my_view
(env:set-active-part my_part)
;; ()
(part:set-distribution-mode #t)
;; #t
(define my_sph1 (solid:sphere (position 0 0 0) 10))
;; my_sph1 => #[entity 1 1]
(define my_sph2 (solid:sphere (position 5 10 20) 10))
;; my_sph2 => #[entity 2 1]
; Name the current state.
(roll:name-state "first_branch")
;; "first_branch"
; roll back to before this creation
(roll "start")
;; 2
; Any modeling created from now on goes into a
; new history stream.
(define my_block (solid:block
   (position -5 10 -20) (position 5 -10 20)))
;; my_block => #[entity 3 1]
; Name the current state.
(roll:name-state "second_branch")
;; "second_branch"
(roll "first_branch")
;; 3
(roll "second_branch")
;; 3

Roll through States

Once states and branches have been defined, they are easily accessed through the roll extension. Several operations can be grouped together as one operation to roll back using the roll:mark-start and roll:mark-end extensions.

roll
Rolls to a previous or later state
roll:mark-end
Marks the end of a block of functions for rolling
roll:mark-start
Marks the start of a block of functions for rolling
roll:name-state
Attaches a name to the current state for rolling

The easiest way of accessing branched states is to name their states and then start roll:name-state with the respectively named states. However, a branch does not have to be named to be accessible.

All of the available branched states can be reached using the roll extension. When using roll, it is important to roll back past the state where the branching begins. Otherwise, roll forward and backward remain on the same branch.

; roll:name-state
; Define a new part
(define my_part (part:new))
;; my_part => #[part 2]

; Define a new view for the part
(define my_view (view:dl my_part))
;; my_view
(env:set-active-part my_part)
;; ()
(part:set-distribution-mode #t)
;; #t

; branching point
(define my_sph1 (solid:sphere (position 0 0 0) 10))
;; my_sph1 => #[entity 1 2]

; one branch
(define my_sph2 (solid:sphere (position 5 10 20) 10))
;; my_sph2 => #[entity 2 2]
; roll back to before this creation
(roll -1)
;; -1

; Any modeling created from now on goes into a
; new history stream.

; second branch
(define my_block (solid:block
    (position -5 10 -20) (position 5 -10 20)))
;; my_block => #[entity 3 2]

; roll back to before this creation
(roll -1)
;; -1

; third branch
(define my_block2 (solid:block
    (position 10 20 30) (position 15 30 45)))
;; my_block2 => #[entity 4 2]

; Go to a point before the branching
(roll "start")
;; 2

; take one branch
(roll "end")
;; 2

; Go to a point before the branching
(roll "start")
;; 2

; take second branch
(roll "end")
;; 2

; Go to a point before the branching
(roll "start")
;; 2
; take third branch
(roll "end")
;; 2

Save History Streams

History streams are saved with the part when the part:save extension is used. The default for part:save is not to save the history stream.

part:save
Saves all entities in a part to a file
part:save-selection
Saves a list of entities to a file; can not save history
part:load
Loads a part from a file into an active part

If the history stream is no longer required, it does not have to be saved to a save file. This is an option on part:save. part:save has an option for the filename to specify both the path and filename. It has additional options for saving the part in a binary or text file, and for saving the history data.

If textmode is #t, the data is saved in text mode. If textmode is not specified, then the mode is determined by the extension of the filename. If the filename string ends in .sab (or .SAB), then the file is saved in binary mode; otherwise, the file is saved in text mode.

After setting textmode, a second Boolean specifies whether to save roll back history data. The default, #f, does not save history.

The "history save" APIs and Scheme extension support saving only the main history stream, without branches. This is done with a "mainline only" argument. If the argument is true, then rolled branches are not saved to the file.

; part:save
; Define a new part
(define my_part (part:new))
;; my_part
(part:set-distribution-mode #t)
;; #t
(env:set-active-part my_part)
;; ()
; ...
; Create model here
; ...
; Save the currently-active part to the named file.
; This saves the part defined earlier in text mode
; and saves history data.
(part:save "test" #t my_part #t)
;; #t

The saved file can be restored at any time using part:load. Obviously, a save file that is loaded that did not contain history streams cannot roll back to previous states.

; part:save
; Define a new part
(define my_part (part:new))
;; my_part
(part:set-distribution-mode #t)
;; #t
(env:set-active-part my_part)
;; ()
; ...
; Create model here
(define my_block (solid:block
    (position 0 0 0) (position 10 10 10)))
;; my_block => #[entity 1 1]
; ...
; Save the currently active part to the named file.
; This saves the part defined earlier in text mode
; and saves history data.
(part:save-selection my_block "test" #t #t)
;; #t

Pruning Branches and States

It is often useful to remove unnecessary branches and states from a given history stream. The following extensions for maintaining states within history streams have various options for exactly what gets removed and from which history stream (if not the default).

roll:delete-all-states
Deletes all delta states
roll:delete-following-states
Deletes all delta states after the current delta state
roll:delete-inactive-states
Deletes all delta states not in the active path from the root to the current one
roll:delete-previous-states
Deletes all delta states before the current one

[Top]

© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.