3.3 Recording And Playback
Sequences of Cubit commands can be recorded and used as a means to control Cubit from ASCII text files. Command or "journal" files can be created within Cubit, or can be created and edited directly by the user outside Cubit.
3.3.1 Journal File Creation and Playback
3.3.1.1 Recording a Session
Command sequences can be written to a text file, either directly from Cubit or using a text editor. Cubit commands can be read directly from a file at any time during Cubit execution, or can be used to run Cubit in batch mode. To begin and end writing commands to a file from within Cubit, use the command
record ’<filename>’
Once initiated, all commands are copied to this file after their successful execution in Cubit.
3.3.1.2 Replaying a Session
To replay a journal file, issue the command
playback ’<filename>’
Journal files are most commonly created by recording commands from an interactive Cubit session, but can also be created using automatic journaling or even by editing an ASCII text file. Commands being read from a file can represent either the entire set of commands for a particular session, or can represent a subset of commands the user wishes to execute repeatedly. Two other commands are useful for controlling playback of Cubit commands from journal files. playback from a journal file can be terminated by placing the stop command after the last command to be executed; this causes Cubit to stop reading commands from the current journal file. Playback can be paused using the Pause command; the user is prompted to hit a key, after which playback is resumed. Journal files are most useful for running Cubit in batch mode, often in combination with the parameterization available through the APREPRO capability in Cubit. Journal files are also useful when a new finite element model is being built, by saving a set of initialization commands then iteratively testing different meshing strategies after playing that initialization file.
3.3.2 Controlling Playback of Journal Files
The following commands control the playback of Journal Files:
stop pause sleep <duration_in_seconds> resume [<n>] where next [<n>]
The playback of a journal file can be interrupted in two ways. If the stop or pause commands are encountered in the journal file and Cubit is reading commands from a terminal (as opposed to a redirected file), playback of the journal file will halt after that command. The sleep command pauses execution for the specified number of seconds. It can be used to build a delay into journal files during presentations. If journal files that are playing back contain playback commands themselves, there may be multiple current journal files. The where lists all current journal files and where the journal files have paused. Each line contains the stack position (a number), the filename and the current line in the file. Unless Cubit is running in batch mode, the first line is always <stdin>. This just means that Cubit will return to the command prompt after the top-most journal file has completed. The remaining portion of any active journal file may be skipped by specifying the stack position (first number on each line of the output from the where command) of the file where you want to resume. Any remaining commands in active journal files with lower stack positions will be skipped. The next command steps through interrupted journal files line-by-line. The argument to the next command is the number of lines to read before halting playback again. If no number is specified, the command will advance one line. Journal playback can also be set to stop automatically when it encounters an error during playback. The command syntax is:
set stop error {on|OFF}
Setting the stop error to "on" will cause the file to halt for each error. The setting is turned off by default.
3.3.3 Automatic Journal File Creation
3.3.3.1 Controlling Automatic Journal File Creation
By default, Cubit automatically creates a journal file each time it is executed. The file is created in the current directory, and its name begins with the word "Cubit " or "history", depending on the version of Cubit, followed by a number starting with cubit01.jou and continuing up to a maximum of cubit999.jou. It is recommended that the user keep no more than around 100 journal files in any directory, to avoid using up disk space and causing confusion. To that end, when the journal name increments to more than cubit99.jou, a warning will be given on startup telling the user that there are at least 99 journal files, and to please clean out unused files. If the user has up through cubit999.jou, then the user is warned that there are too many journal files in the current directory, and cubit999.jou will be re-used, destroying the previous contents. When starting Cubit, the choice of journal file name to be used depends on whether it is creating a historyXX.jou file, or a cubitXX.jou file. For historyXX.jou files, it will look for the highest used number in the current directory and increment it by one. For example, if there are already journal files with names history01.jou, history02.jou, and history04.jou, Cubit will use history05.jou as the current journal file. For cubitXX.jou files, Cubit will fill in gaps, starting with the lowest number. For example, if there are already journal files with names cubit01.jou, cubit02, jou, and cubit04.jou, then Cubit will use cubit03.jou as the current journal file. Journal file names end with a ".jou" extension, though this is not strictly required for user-generated journal files. If no journaling is desired, the user may start Cubit with the -nojournal command line option or use the command :
[set] journal {off | on}
Turning journaling back on resumes writing commands to the same journal file. Most Cubit commands entered during a session are journaled; the exceptions are commands that require interactive input (such as Zoom Cursor), some graphics related commands, and the playback command.
3.3.3.2 Recording Graphics Commands
journal graphics {on | off}
The default is journal graphics off .
3.3.3.3 Recording Entity IDs and Names
When an entity is specified in a command using its name, the command may be journaled using the entity name, or by using the corresponding entity type and id. The method used to journal commands using names is determined with the command:
journal names {on | off}
The default is journal names on . If an entity is referred to using its entity type and id, the command will be journaled with the entity type and id, even if the entity has been named.
3.3.3.4 Recording APREPRO Commands
[set] journal [graphics|names|aprepro|errors] [on|off]
See APREPRO Journaling for more information.
3.3.3.5 Recording Errors
journal errors {on|OFF}
## create brick x 10 x 10 z 10
Since Cubit recognizes this as erroneous syntax, it will issue an error when the command is issued, but will still write the command to the journal file as a comment, prefixing the command with "##". This option may be useful when tracking or documenting program errors.
3.3.4 Idless Journal Files
Journal files can also be created without reference to entity IDs. The purpose of this command is to enable journal files created in earlier versions of Cubit to be played back in newer versions of Cubit. Using the "IDless" method, commands entered with an entity ID will be journaled with an alternative way of referring to the entity. Changes in Cubit or ACIS often lead to changes in entity IDs. For example, a webcut may result in volume 3 on the left and volume 4 on the right. In another version of Cubit, those entity IDs may be swapped (4 on the left and 3 on the right). Playing an IDless journal file makes the actual ID of an entity irrelevant. The syntax for this command is:
[set] journal Idless {on|off|reverse}
The on option will enable idless journaling, and commands will be journaled without entity IDs. For example, "mesh volume 1" may be journaled as "mesh volume at 3.42 5.66 6.32 ordinal 2". Selecting the off option will cause commands to be journaled in the traditional manner (i.e., as they are entered). The reverse option allows you to convert idless journal files back into an ID-based journal file where the new journal file will reflect current numbering standards for IDs. If you issue the command journal Idless without any additional options, then the current status of ID journaling is printed. At startup, this should be "off". The most likely scenario for converting older journal is to use the record command during playback. The following is an example.
journal idless on |
record "my_idless.jou" |
playback "my_journal.jou" |
record stop |
journal idless off |
To record an idless journal file back into an id-based journal file you might use the following sequence.
journal idless reverse |
record "new_id_based.jou |
playback "my_idless.jou" |
record stop |
journal idless off |
IDless conversions of APREPRO expressions are partially supported.