4.3. File Handling
File handling deals with issues relating to manipulation of design files within SCE. File handling includes opening, saving, and closing of actual design model files on disk. File handling is closely related to Design Windows (Section 3.3) and Design Window Management (Section 4.8). In general, there is a one-to-one association between design models, design files on disk and design windows in the Workspace. Each Design Window represents a view onto one loaded design file which in turn stores the data of one design model, and vice versa. For example, both file closing (Section 4.3.3) and window closing (Section 4.8) will close the design file and the design window and unload the design from SCE's memory.
SCE operates on design files stored in SpecC Internal Representation (SIR, *.sir) format on disk. On the other hand, in order to exchange design files with other tools, SCE supports importing and exporting of files in SpecC source code format (*.sc). During file import and export, SCE will run the SpecC compiler (see Appendix D) to translate SpecC source files into SIR format and vice versa.
Specifically, file handling consists of the following tasks:
File Opening to open and load existing design files from disk (see Section 4.3.1).
File Saving to save a design into a design file on disk (see Section 4.3.2).
File Closing to close a design file (see Section 4.3.3).
File Importing to open and load an existing external design in SpecC source format (see Section 4.3.4).
File Exporting to save a design into an external design file in SpecC source format (see Section 4.3.5).
Design Properties viewing to display and edit the current design file's properties (see Section 4.3.6).
SCE Exiting to exit the SCE application (see Section 4.3.7).
4.3.1. File Opening
Operation: Users can open an existing design file on disk in different ways:
Selecting Main::File->Open... will pop up the File Open dialog in which the user can choose and select an existing file on disk to open and load. The File Open dialog is illustrated in Figure 4-8.
Users should first specify the directory of the file in Look-in box. The content of the directory will be automatically displayed in the display box in the center. The file type defaults to SIR files (*.sir). All the files with the specified type will be displayed in the display box. Users then further select the file name in the File Name box. Finally, by clicking the Open button, the file with the specified name will be open. If users click the Cancel button, the action of file opening will be cancelled. Either clicking Open or Cancel button will close the File Open dialog.
Double-clicking on a design in the Project Window models or imports tabs (Project::Models or Project::Imports) or selecting the corresponding context-menu entries (Project::Models->Open or Project::Imports->Open) will open and load the design file for the selected design model.
Opening and loading a design file in either way will result in a corresponding new Design Window popping up in the Workspace. The new Design Window will automatically be made the active one and raised to the front of the Workspace.
If the selected design file is already opened and loaded, it will not be loaded again from disk and file opening will only result in activating and raising of the corresponding Design Window in the Workspace.
Error/Information Messages: In the case of selecting from disk, if the specified file does not exist before clicking the Open button, then clicking Open has no effect.
In case of errors reading the design file from disk (file errors, wrong file format), an error dialog with a corresponding error message is popped up. Upon confirming the error, the file opening action is cancelled.
4.3.2. File Saving
Operation: Users can save opened and loaded design files (Design Windows in the Workspace) by one of the following three methods:
Selecting Main::File->Save will save the file of the currently active Design Window using its current name.
Users can save the file of the currently active Design Window under any (new) name by selecting Main::File->Save As.... The selection will pop up the File Save dialog in which user can choose the directory and file name to save the design under. The File Save dialog is shown in Figure 4-9.
In the File Save dialog, users should first specify the directory of the file in Look-in box. The content of directory will be automatically displayed in the display box in the center. The file type defaults to SIR files (*.sir). All the files with the specified type will be displayed in the display box. Users then further select the file name in File Name box. Finally, by clicking Save button, the current opened file will be saved as the file with the specified name. If users click Cancel button, then the action of file saving will be cancelled. Either clicking Save or Cancel button will close the File Save dialog.
Selecting Main::File->Save All will save the files of all currently opened Design Windows in the Workspace using their current names.
Error/Information Messages: When selecting Main::File->Save As... and specifying the file name of an existing file on disk, an Information dialog will pop up asking the user whether he wants to overwrite the existing file. If the user declines this, the file saving action will be cancelled.
When selecting Main::File->Save, Main::File->Save As..., or Main::File->Save All, errors may occur (file errors, e.g. if no space is available on the disk). In this case, an Error dialog as shown in Figure 3-9 will be popped up, corresponding error messages will be displayed, and the file saving action will be cancelled.
4.3.3. File Closing
Operation: Users can close the file and window of the currently active Design Window in the Workspace by selecting Main::File->Close. Closing a file will unload the design from memory and will close the corresponding Design Window in the Workspace.
Error/Information Messages: If the current design is modified and not yet saved, selecting Close will pop up an Information dialog which recommends to save the current design first. If the user accepts the recommendation, a file saving action (Section 4.3.2) is performed before closing the file.
4.3.4. File Importing
Operation: Users can import and open an existing design file in external source code format on disk by selecting Main::File->Import.... This will pop up the File Import dialog in which the user can choose and select an existing SpecC source file on disk to open and load. The File Import dialog is illustrated in Figure 4-10.
Users should first specify the directory of the file in Look-in box. The content of the directory will be automatically displayed in the display box in the center. The file type defaults to SpecC source files (*.sc). All the files with the specified type will be displayed in the display box. Users then further select the file name in the File Name box. Finally, by clicking the Open button, the file with the specified name will be imported. If users click the Cancel button, the action of file importing will be cancelled. Either clicking Open or Cancel button will close the File Import dialog.
After clicking the Open button, the SpecC compiler command line tool will be executed to preprocess and compile the SpecC source code into a corresponding SIR file with the same base name. Any diagnostic, status and informative output of the SpecC compiler will be shown in the compiler tab of the Output Window (Output::Compile).
After preprocessing and compilation, the compiled SIR file will be opened and loaded, i.e. triggering a file opening action (Section 4.3.1). This will result in a corresponding new Design Window popping up in the Workspace. The new Design Window will automatically be made the active one and raised to the front of the Workspace.
If a SIR file with the given name is already opened and loaded, file importing will activate, raise and reload the existing Design Window in the Workspace.
Error/Information Messages: If the specified file does not exist before clicking the Open button, then clicking Open has no effect.
If the SpecC compiler aborts with a preprocessing or parsing error or if the compiler killed via the Main::Synthesis->Stop menu entry, a corresponding error message will be shown in Output::Compile and an Error dialog will pop up. Furthermore, if errors occur during opening the compiled design file from disk (file errors, wrong file format), an error dialog with a corresponding error message is popped up. Upon confirming any of the errors, the remainder of the file importing operation will be cancelled.
4.3.5. File Exporting
Operation: Users can save opened and loaded design files (Design Windows in the Workspace) in SpecC source format as corresponding source files on disk by selecting Main::File->Export.... The selection will pop up the File Export dialog in which user can choose the directory and file name to save the design under. The File Export dialog is shown in Figure 4-11.
In the File Export dialog, users should first specify the directory of the file in Look-in box. The content of directory will be automatically displayed in the display box in the center. The file type defaults to SpecC source files (*.sc). All the files with the specified type will be displayed in the display box. Users then further select the file name in File Name box. Finally, by clicking Save button, the current opened file will be exported to the file with the specified name. If users click Cancel button, then the action of file exporting will be cancelled. Either clicking Save or Cancel button will close the File Export dialog.
In the File Export dialog, users can specify several options for content and formatting of the generated SpecC source code output. Extra information (Meta data group) that can optionally be generated in the SpecC output file includes the following:
- Line info
Determines whether the output source code will include line number information (#line directives) tracing back to the originally imported source code.
- Annotations
Determines whether the output source code will include SpecC annotations (note statements).
- Tab step
Determines level of indentation (number of spaces) for each level of nested blocks. A value of zero turns off indentation completely.
- System tab
Specifies the number of spaces in a system tab (ASCII 009, \t) character. In case of a non-zero value, indentation in the output code will be produced by inserting system tab steps whenever possible. A value of zero turns off use of system tabs and uses only spaces for indentation.
- Line wrap
Specifies the maximum number of characters in an output line. Lines longer than this amount will be wrapped into a new line. A value of zero turns off line wrapping completely.
Error/Information Messages: When selecting Main::File->Export... and specifying the file name of an existing file on disk, an Information dialog will pop up asking the user whether he wants to overwrite the existing file. If the user declines this, the file exporting action will be cancelled.
When writing files to disk, errors may occur (file errors, e.g. if no space is available on the disk). In this case, an Error dialog will be popped up, corresponding error messages will be displayed, and the file exporting action will be cancelled.
4.3.6. Design Properties
Operation: Users can display and view a design's properties by selecting Main::Project->Properties.... The selection will pop up a Design Properties dialog which is illustrated in Figure 4-12.
In the Design Properties dialog, the box Design Name displays the design name, the box File Name displays the name of the design file, and the box Change Log displays the history of SCE refinement commands applied to the design. The left part of the Change Log specifies which commands were executed. The right part of Change Log specifies the exact command lines with parameters. Clicking button Ok will close Design Properties dialog .
4.3.7. SCE Exiting
Operation: Selecting Main::File->Exit will exit the SCE application and close the SCE GUI.
The current project, if any, will be automatically saved by triggering a project saving action (see Section 4.2.3). Note that this can result in a Project Save dialog popping up in case the current project is unnamed and modified.
Error/Information Messages: If there are any open Design Windows that are modified and not yet saved, an Information dialog will pop up for each window, querying the user whether he wants to save the corresponding design. The user will be able to cancel the whole exit action via the corresponding dialog button. If the user accepts the recommendation to save the file, a file saving action will be triggered (see Section 4.3.2). Note that the file saving action can trigger additional Error dialogs which in turn can abort the whole exit operation in case of file errors during saving.
Automatic project saving can result in errors and corresponding Error dialogs popping up. In turn, the whole exit operation can be aborted in those cases.