Archive Reporter
Navigation: User Guide ➔ Reports ➔ Archive Reporter
| Archive Reporter | Archive Editor | Archive (sac) File Text Format |
|---|
Related Links: Planning Example Project, Tailings Dam Example Project, Waste Handling with Batch Digestion Example Project
Introduction
The Archive Reporter is used with Dynamic projects to report data directly to a database, CSV or text file while a project is running. This has some similarities with the SysCAD Historian, however the archiver has significantly greater functionality so the use of the historian for reporting is not recommended.
The user specifies how many tables of data are required (maximum is 500), the frequency of reporting (each table may be reported at a user specified time) and the tags that are reported in each table. These settings are recorded in a text file by the Archive Editor. The maximum number of Fields (including Time Fields) in a Table is 2000 (for DB-SQLITE .db3 format) and 3000 (for csv format).
Please also note that this file is loaded (or reloaded) from the Project Settings Archive tab page, as shown in the sections below.
Archive Configuration
To use the Archiver:
- Go to Edit - Project Settings
- The dialogue box shown below will be displayed
- Go to the Archive page and tick the 'On' box
- The SysCAD Archive Configuration (.sac) file will be created
- Click on the 'Edit' button to edit the Archive.sac file
The Settings are explained in the table below:
| Setting / Tick Box | Description |
Archive Reporter Configuration | |
| On | The user must tick this box to enable the Archive Reporter. |
| Name | This will be the name of the Archive Reporter file. The default name is Archive.sac and it is automatically created in the project folder when the user ticks the 'On' box. Users can choose to have a different file name but only one sac file can be used per project. |
| Browse | The user may browse for an alternative Archive file using this button. |
Press the Edit button to launch the Archive Editor.
Pressing the Reload button loads the Archive.sac file into SysCAD, which will check the file and display messages in the Messages window.
System Settings
The Settings are explained in the table below:
| Setting / Tick Box | Description |
Time Fields | |
| Date and Time | Every table will contain a column with the simulation time and date for the reported values. The format for this column will be Date:Time |
| Date Only | Every table will contain a column with the simulation date for the reported values. |
| Time Only | Every table will contain a column with the simulation time for the reported values. |
| Elapsed as HMS | Every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be hh:mm:ss |
| Elapsed Time | Unless the user selects 'Off', every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be a single value, and will display the total elapsed time as seconds, minutes, hours or days, depending on the user selection. |
System Tables | |
| Message Log | If the user ticks this box, all simulation messages will be written to a log file in the Archive folder. |
| Event Log | If the user ticks this box, all Events will be written to a log file in the Archive folder. |
| Standard Fields These tick boxes determine what information is written to the Message Log file. | |
| Source | The source of the message will be logged. |
| Tag | The unit tag that is source of the message will be logged. |
| Command | All SysCAD commands will be logged, e.g. 'Stop', 'Run', etc. |
| Type | The type of message will be logged, i.e. Error, Warning, etc. |
| Message | Messages will be displayed. If this is not ticked, then only Errors and Warnings will be logged. |
| ID No | The ID of the message will be logged. |
| Iteration | The Iteration of the message will be logged. |
| Call No | The Call number for the message will be logged. |
| Sequence No | The Sequence number of the message will be logged. |
Reporting Options
| Field | Option | Description |
| On | If On = 1, the table will be created. If On = 0, the table will not be created. | |
| Name | The name of the table (for DB formats) or name of the file for csv/txt file formats. | |
| Format | DB-SQLITE | Data will be saved in Archive.db3 SQ Lite database in the project folder (Maximum fields per table is 2000) |
| DB-MSACCESS | Data will be saved in Archive.mdb Microsoft Access database in the project folder | |
| CSV | Data will be saved in a CSV file (Maximum fields per table is 3000) | |
| TXT | Data will be saved in a Text (txt) file | |
| Clear | Rewind | Clear archive file on next run. |
| False | Add to existing archive file on next run. This can be overridden by other settings on the Solver Setting - Scenario page such as the RestartArchive option. | |
Note: Each table can only have one format but within the same archive file, different tables can have different formats
CSV and TXT File Options
If the Format chosen is CSV or TXT, then the following options are relevant.
| Field | Description |
| Path | The path and folder name for storing CSV & TXT files (usually with the Project) |
| SigDigits | The number of significant digits for the tags that are reported to CSV & TXT files. Recommendation is 16. Accepted range is 2-17. |
Period and Offset
The Period and Offset for reporting can be specified. This is not required if the user specifies a Trigger, but note that both Periods and Triggers can be used for the same table.
| Field | Description |
| Period | Time frequency for reporting fields, where time zero is at start. Note 1: The period is relative to midnight, not the simulation start time. Note 2: If the period is not divisible by 24 hours, the reporting will not be at the same time each day. |
| Offset | Time offset within the specified period. This affects when the first set of data is recorded. Note: The offset is relative to midnight, not the simulation start time. |
Notes:
- Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (i.e. report specified fields based on trigger logic).
- If one or more Triggers are used, a period & offset is not relevant or required.
- If no triggers or period are specified then the table will not accumulate data.
- Note that period and offset are relative to midnight. If your start time is not on a reporting period relative to midnight AND you want to report relative to the start time, then you need to specify an offset to achieve this. For example, if you want to report every 24 hours and the start time is 8:00am, then the offset should be 8 hours.
Trigger Options
The user may specify one or more Triggers that will cause the values in the table to be reported. There can be any number of triggers. If the conditions of any of the triggers are met, then the fields will be reported.
The triggers are numbered and include three terms as described below, a description, a SysCAD tag and the Trigger Test.
| Term | Option | Description |
| Description | A description of the trigger | |
| SysCADTag | Any valid SysCAD tag. May have conversions. | |
| TriggerTest | Rise = Value | The trigger will be true if the value has increased by more than the specified amount since the last recorded value. The last recorded value will either be the first value or the value when the trigger was last true. |
| StepRise = Value | The trigger will be true if the value has increased by more than the specified amount since the last step. | |
| Fall = Value | The trigger will be true if the value has decreased by more than the specified amount since the last recorded value. The last recorded value will either be the first value or the value when the trigger was last true. | |
| StepFall = Value | The trigger will be true if the value has decreased by more than the specified amount since the last step. | |
| Delta = Value | The trigger will be true if the value has changed by more than the specified amount since the last recorded value. The last recorded value will either be the first value or the value when the trigger was last true. | |
| StepDelta = Value | The trigger will be true if the value has changed by more than the specified amount since the last step. | |
where = Value = Test value used to see where there are sudden changes.
Notes:
- Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (i.e. report specified fields based on trigger logic).
- If one or more Triggers are used, a period & offset is not relevant or required.
- If no triggers or period are specified then the table will not accumulate data.
Field Options
The user may specify one or more fields in the table to be reported.
The fields are numbered and include five terms as described below, a field name, a SysCAD tag, a function, measure point and first point options.
| Term | Option | Description |
| FieldName | Report column or field name. Should not contain characters: '.,[] | |
| SysCADTag | Any valid SysCAD tag. May have conversions. | |
| Function | Current/Cur | Returns the current value. |
| CurrentDiff/CurDiff | Returns the difference between current value and the current value at the end of the previous reporting period. | |
| Minimum/Min | Returns the minimum value for the chosen period. | |
| Maximum/Max | Returns the maximum value for the chosen period. | |
| Average/Avg | Returns the average value for the chosen period. | |
| AverageTotal/AvgTtl | Returns the average value since the beginning of the run. | |
| Sum | Returns the total of the reported tag for the report period. Note: The SysCAD tag MUST be on a per second basis (e.g. P_1.Qm (t/s)). | |
| SumTotal/SumTtl | Returns the total of the reported tag since the beginning of the run. Note: The SysCAD tag MUST be on a per second basis (e.g. P_1.Qm (t/s)). | |
| ReportTime | Returns the number of seconds for the report period. This will be equal to the number of steps in the report period multiplied by the timestep. Any valid SysCAD tag can be specified. | |
| SimulationTime | Returns the number of seconds since the beginning of the run. This will be equal to the total number of steps since the beginning of the run multiplied by the timestep. Any valid SysCAD tag can be specified. | |
| Time(operator,value,[timeunit]) | Returns the amount of time in the report period that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d. | |
| TimeTotal(operator,value,[timeunit]) /TimeTtl(operator,value,[timeunit]) |
Returns the amount of time since the beginning of the run that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d. | |
| TimeInRange(low operator,low value,high operator,high value,[timeunit]) | Returns the amount of time in the report period that the reported tag is within the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d. | |
| TimeInRangeTotal(low operator,low value,high operator,high value,[timeunit]) | Returns the amount of time since the beginning of the run that the reported tag is within the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d. | |
| TimeOutRange(low operator,low value,high operator,high value,[timeunit]) | Returns the amount of time in the report period that the reported tag is outside the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d. | |
| TimeOutRangeTotal(low operator,low value,high operator,high value,[timeunit]) | Returns the amount of time since the beginning of the run that the reported tag is outside the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d. | |
| Count/Cnt | Returns the number of recorded values for the report period. This will be equal to the number of steps in the report period. Any valid SysCAD tag can be specified. | |
| ChangeCount/ChgCnt | Returns the number of times the reported tag changed by more than 0.001 (in SI Units) during the report period. | |
| String/Str | Returns the current value of a string. Note: the SysCAD tag must be a string. | |
| MeasurePt | StartPt | The value of the SysCAD tag at the beginning of a step. |
| EndPt | The value of the SysCAD tag at the end of a step. | |
| MidPt | The value of the SysCAD tag halfway through the step. | |
| FirstPoint | IgnoreFirst | Ignores the first value at the start of the run. i.e if the first value for the tank is 0 and it goes to 29 at the end of the first step, 29 will be recorded as the first value if the IgnoreFirst option is used. |
| UseFirst | Use the first value at the start of the run. | |
Archive Options
To see the Archive Options dialog box, go to Tools - Archive Options.
The Archive Options dialog box shows the tables that have been created and their frequency of data recording. The following dialog box is generated using the example described above.
Example Archive Enabled Projects
A few example projects with Archive enabled are included with the standard install. These include: