3.2.2. Read State Files

>readstate [mode=<overwrite | append>][filename=<filename>, load=<true | false>]

The >readstate command loads an Ansys TurboGrid State from a specified file.

If a DATA READER singleton has been stored in the state file, the load action loads the contents of the results file. If a state file contains BOUNDARY Objects, and the state file is appended to the current state (with no new DATA READER Object), some boundaries defined may not be valid for the loaded results. BOUNDARY objects that are not valid for the currently loaded results file are culled.

>readstate supports the following options:

  • mode = <overwrite | append>

    If mode is set to overwrite, the executor deletes all the objects that currently exist in the system, and loads the objects saved in the state file. Overwrite mode is the default mode if none is explicitly specified. If mode is set to append, the executor adds the objects saved in the state file to the objects that already exist in the system. If the mode is set to append and the state file contains objects that already exist in the system, the following logic is used to determine the final result: If the system has an equivalent object, that is, name and type, then the object already in the system is modified with the parameters saved in the state file. If the system has an equivalent object in name only, then the object that already exists in the system is deleted, and replaced with that in the state file.

  • filename = <filename>

    The path to the state file.

  • load = <true | false>

    If load is set to true and a DATA READER object is defined in the state file, then the Results file is loaded when the state file is read. If load is set to false, the results file is not loaded, and the DATA READER object that currently is in the object Database (if any) is not updated.

The following table describes the options, and the corresponding action taken on the objects and the DATA READER.

Mode Selection

Load Data Selection

What happens to the Objects?

What happens to the DATA READER?

Overwrite

True

All user objects are deleted. The loading of the new results file changes the default objects (boundaries, wireframe, and so on) including deletion of objects that are no longer relevant to the new results. Default objects that are not explicitly modified by object definitions in the state file have all user modifiable values reset to default values.

It is deleted and replaced.

Overwrite

False

All user objects are deleted. All default objects that exist in the state file update the same objects in the current system state if they exist. Default objects in the state file that do not exist in the current state are not created. All user objects in the state file are created.

If it exists, it remains unchanged regardless of what is in the state file.

Append

True

No objects are initially deleted. The default objects in the state file replace the existing default objects. User objects:

  • are created if they have a unique name.

  • replace existing objects if they have the same name but different type.

  • update existing objects if they have the same name and type.

It is modified with the new value from the state file.

Append

False

No objects are initially deleted. Default objects in the state file only overwrite those in the system if they already exist. User objects have the same behavior as the Append/True option above.

If it exists, it remains unchanged regardless of what is in the state file.

 

3.2.2.1. readstate Command Examples

The following are example >readstate commands, and the expected results. If a STATE singleton exists, the values of the parameters listed after the >readstate command replace the values stored in the STATE singleton object. For this command, the filename command parameter value replaces the state filename parameter value in the STATE singleton, and the mode command parameter value replaces the readstate mode parameter value in the STATE singleton.

> readstate

This command overwrites or appends to the objects in the system using the objects defined in the file referenced by the state filename parameter in the STATE singleton. If the STATE singleton does not exist, an error is raised indicating that a filename must be specified.

> readstate filename = mystate.tst

The readstate mode parameter in the STATE singleton determines if the current objects in the system are deleted before the objects defined in the mystate.tst file are loaded into the system. If the STATE singleton does not exist, then the system objects are deleted before loading the new state information.

> readstate mode = overwrite, filename = mystate.tst

This command deletes all objects currently in the system, opens the mystate.tst file if it exists, and creates the objects as stored in the state file.

> readstate mode = append, filename = mystate.tst

This command opens the mystate.tst file if it exists, and adds the objects defined in the file to those already in the system following the rules specified in the above table.

> readstate mode = overwrite

This command overwrites the objects in the system with the objects defined in the file referenced by the state filename parameter in the STATE singleton. If the STATE singleton does not exist, an error is raised indicating that a filename must be specified.

> readstate mode = append

This command appends to the objects in the system using the objects defined in the file referenced by the state filename parameter in the STATE singleton. If the STATE singleton does not exist, an error is raised indicating that a filename must be specified.