The FileWrapper utility enables users to create Analysis Server components from file I/O programs. These components are often referred to as FileWrapper components.
In its simplest form, a file I/O program is an analysis that has one input file, an executable that can be run from the command line of an operating system shell, and one output file.
Typically, a user modifies values within the input file, runs the program, and extracts values from the output file. More complicated file I/O programs may have multiple input files and/or output files associated with either a single executable or multiple executables. With these programs, many files may need to be modified or analyzed during each execution of the analysis.
Many file I/O programs (particularly CAD systems, finite element packages, and other graphically based analysis programs) do not operate in the typical fashion, where its users are forced to manually edit its input and output files. Instead, they operate using commands supplied interactively by its users through a graphical user interface (GUI). Some of these programs can be used without the GUI by executing batch files. Others eliminate the need for the GUI with special program files that emulate a sequence of user-supplied commands. These special cases can also be considered file I/O programs, since the batch and program files can be treated as executables.
The FileWrapper utility is designed to automate the execution of analyses that are based on file I/O programs. A FileWrapper component can be created that will automatically edit the appropriate input file(s), run the executable(s), and parse the output file(s) of an analysis whenever the component is executed using the Analysis Server API.
To create a FileWrapper component, simply create a FileWrapper file and associate it with a particular analysis. A FileWrapper file is a text file with a .fileWrapper extension that contains information about how to execute the analysis. Specifically, the FileWrapper file identifies the values within specified input and output files that are to be modified and/or retrieved when the component is executed.
When the Analysis Server encounters a FileWrapper file in its analyses path or in a public_aserver directory, it will automatically create a FileWrapper component using the information contained within this file.
A FileWrapper file is comprised of several sections. At a minimum, a FileWrapper file should contain a Header section that provides descriptive information about the component; a RunCommands section that contains a set of instructions that is completed each time the component is executed; an input file section that contains instructions for locating values within the input file to the component's analysis; and an output file section that contains instructions for locating values within the analysis' output file. Click to view a sample.fileWrapper.
The header section may contain comments and tags. Comment lines begin with the pound sign (#) and are normally inserted as documentation of the FileWrapper file itself. Tags begin with @, and provide users with descriptive information when the describe API command is issued on a component. For more information about API commands, see Analysis Server API.
| @author | Specifies the author of the FileWrapper file. Usually, the resident expert of the analysis that it wraps. |
| @version | Specifies the version of the FileWrapper file. |
| @description | Specifies a short description of the analysis being wrapped. |
| @helpURL | Specifies a URL where users may look to find additional information about the FileWrapper component. |
| @keywords | Specifies keywords that can be used to help locate and identify the FileWrapper component. |
RunCommands { generate inputFile run "myAnalysis.exe" parse outputFile }
There are two types of input file sections: RowFieldInputFile and RawInputFile.
TheRowFieldInputFile section treats an input file as a set of rows, where each line is considered a row. Each row, in turn, is comprised of a set of fields. The author defines an input to the component by defining a variable, and providing its value's row and field location within the input file. When the input file is generated, the values of the inputs are automatically written to the file at the appropriate row and field locations.
By default, the first line within an input file is considered the first row. If a file is lengthy, it may become tedious for the author to specify the row locations of input variables relative to the first row. The markAsBeginning statement enables the author to reset the first row by specifying a character string. The first row that contains this string will be marked as the new first row. Multiple markAsBeginning statements may be used within a RowFieldInputFile section.
By default, whitespace characters divide the rows within an input file into fields. The setDelimiters statement can be used to re-define the characters to be treated as delimiters. Multiple setDelimiters statements may be used within a RowFieldInputFile section.
The author can define input variables to the component using the variable and keyVariable statements. Single dimensional arrays can be defined using the array statement. A name and type must be declared for each variable or array, followed by its row and field location(s) within the input file.
For complete descriptions of these and other statements that can be used within a RowFieldInputFile section, see FileWrapper Statements.
The RawInputFile section treats an entire input file as a single text string. The text string becomes a single input to the component.
Each output file section contains instructions on how to retrieve values from an output file. There are two types of output file sections: RowFieldOutputFile and RawOutputFile. These types are structured similarly to the RowFieldInputFile and RawInputFile sections, respectively. All statements that apply to input file sections also apply to output file sections.
The only difference between the input file sections and the output file sections is that the fileToParse statement replaces the templateFile and fileToGenerate statements. This statement is used to specify the name of the file that contains the specified outputs.
Before creating a FileWrapper component from a particular analysis, the author of the component should make sure of the following:
The process of creating a FileWrapper component can be broken down into three steps:
Before the FileWrapper file that defines the component can be created, the analysis executable, its input file(s), and its output file(s) must be identified. To create a component, the author will need to know how to properly create and modify the input file(s), and be familiar with how different input file options affect the output file(s). The author should also know how to run the executable and interpret the results.
The FileWrapper file is a text file that instructs the Analysis Server where to find variables in the input and output files, and how to run the analysis. Each FileWrapper file should contain a Header section, one or more Input File sections, a RunCommands section, and one or more Output File sections. For detailed information about each of these sections, see The Structure of a FileWrapper File.
Once completed, the FileWrapper file should be stored in a directory within the server's analyses path, or in a public_aserver directory.
The first step in testing a FileWrapper component should be to test all commands used as arguments to the run statement within the RunCommands section(s). From an operating system shell, change to the directory in which the FileWrapper file is located, and type each command. Make sure the command executes the component's analysis program. The program should access the correct input files and produce the correct output files in the appropriate directories. If the program does not execute properly, then it will certainly fail to execute properly when the component attempts to use the identical command to execute it.
The author should then use whatever test cases exist for the analysis pogram to test the component in the Analysis Server. The component should be instanced in an Analysis Server interactive session, all of its input variables should be set according to the test case values, and the component should be run. If the outputs provided by the Analysis Server differ from the outputs expected, then the author must troubleshoot the component to determine and correct the source of the discrepancy.
See also Analysis Server | FileWrapper Statements
#
# example FileWrapper Header
#
# these are comment lines
#
# @author: Phoenix Integration
# @version: Training
# @description: description of my analysis
#