The Local Name and toOption

When a component executes locally or on a SIMULIA Execution Engine station (when connected to a SIMULIA Execution Engine), a local Working Directory is created that is unique to that instance of that component. The local working directory is necessary to allow parallel execution of models. The only way to access the data of a file parameter is through a file name. Except for a special case involving a File Handler, the data pointed to by a file parameter must be copied into the working directory or another directory on the local computer before the component can be run.

Before the component is run, the working directory is created and all Input file parameters (except as noted below) are copied from the Handler into the working directory. After the component finishes executing (assuming it did not fail execution), all Output file parameters are copied from the working directory into the Handler (except as noted below).

The name given to the copy of the data in the working directory is controlled by the Local Name of the file parameter and by an integer setting, the toOption.

The Local Name and toOption setting are tied to the component that owns the File Parameter. They are not copied when file parameters are mapped from one component to another. You must configure the toOption for every file parameter, whether or not it is mapped (a Local name may or may not be set, depending on how the toOption is set).

For example, if a file parameter F is mapped from component A (where it is an output) to component B (where it is an input), when component B executes, the Handler will come from the settings of F in A but the Local Name and toOption will come from the settings of F in B.

The basic rules for copying File Parameters to/from the Working Directory are:

  • If a Local Name is set, the data are always in the working directory with the name given by the Local Name while the component is executing. Input parameters are copied into a file with the Local Name before the component starts, and output parameters are copied from a file with the Local Name after the component finishes. It is possible for the Local Name to be an absolute path, in which case the data do not actually reside in the Working Directory; the data are still copied in or out as described above. This option is useful when the component requires the file to have a specific name, either because of how the component was written or to make it clear to a person using the model what is going on.

  • If no Local Name is specified and the handler is not a File Handler, Isight assigns a Local Name for the file parameter and behaves as described above. The name is arbitrary (it is currently the name of the file parameter with an extension appropriate to the contents of the file) so that data from an InLine Handler or URL Handler can be accessed as a local file even if the Model does not require a specific file name.

  • If no Local Name is specified and the handler is a File Handler, the data are never copied. Instead, the file path configured into the File Handler is passed to the component, allowing the component to read from the original file location. Output file parameters are written directly to their final location, which can be a big performance improvement for components that read and write very large files. However, the process puts a large burden on the Model Assembler to allocate space for the files and to ensure that the files can be accessed from all the SIMULIA Execution Engine stations involved in running the model when using the SIMULIA Execution Engine environment.

The above rules can be modified by setting the toOption. This setting, which is different for Input and Output file parameters, indicates if the Local Name is used and if the data are copied. The possible values of the toOption are defined in the interface com.engineous.sdk.vars.FileValueType:

  • INPUT_OPTION_AUTO

    (Input file parameters only.) No Local Name is specified. A File Handler input file parameter will not be copied into the working directory. Any other type will be copied into the working directory with a name created by Isight.

  • INPUT_OPTION_FIXED_FILENAME

    (Input file parameters only.) A Local Name must be specified. The data will always be copied into the Working Directory, even for a File Handler.

  • OUTPUT_OPTION_LOCATION

    (Output file parameters only.) The data will be copied from the Working Directory into the Handler. The Handler must be configured when the File Parameter is created. If a Local Name is configured, the file will have that name in the Working Directory; if no Local Name is configured, one will be generated. If no Local Name is configured and a File Handler is configured, no Local Name is created, Instead, the name configured into the File Handler is passed to the component so that the component can write the data directly into its final location. This value is the most flexible option for an Output file parameter but is the most complex to configure.

  • OUTPUT_OPTION_FILEMGR

    (Output file parameters only.) This option is the “Isight File Manager” case described above. No Handler is configured. Instead, Isight creates a Handler at run time that will store the data with the Run Results. A Local Name may or may not be specified. If none is specified, one is created by Isight. The component always writes the file into the Working Directory. This option is the simplest type of Output File Parameter to configure because you do not have to worry about where the data are going to be stored—Isight handles everything. With this option, the size of the file is limited only by available disk space—in the local database directory for local execution, in the SIMULIA Execution Engine FileMgr directory for distributed execution.

  • OUTPUT_OPTION_AUTO

    (Output file parameters only.) A Local Name must be supplied. The component writes the data directly to the location specified by the Local Name, which is usually an absolute path to a shared file system but can be a relative path in the Working Directory in some cases. No Handler is configured in the File Parameter. Instead, when the component finishes executing, a File Handler is automatically created and configured to point to the absolute path of the Local Name. The intent is that the component will write the file to a specified location (the Local Name), and the location of that file is passed on to subsequent components with no copying of the data. Use of this option has the same net effect as using OUTPUT_OPTION_LOCATION with a configured File Handler and no Local Name, but it is easier to set up and (may be) easier to think about. If a relative path is used for the Local Name, the file will be left in the Working Directory. Typically, the Working Directory is deleted once the component finishes executing, which would delete the file. In addition, the Working Directory is usually not on a shared file system, so a relative path will work only in desktop (Standalone) mode or if the component Affinities are set to force the next component to run on the same SIMULIA Execution Engine station as the component writing the file when running on a SIMULIA Execution Engine.