Parameterized Phrases
The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.
Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to Report Building (Report Studio)
Parameterized phrases are used for any customizable wording within a report, including:
- The header text of any column
- The display of time and date information
- Any text that you add to the body of the report
Phrases can be a mixture of plain text and parameters. A text %[token] holds the place of the selected parameter. The %[token] is replaced by a live value when the report is run. All other text is passed through exactly as written. Parameters are not required, the parameterized phrase dialog will accept a phrase that is plain-text only.
Any field that accepts parameterized phrases will have a button right-of-field featuring a blue and white dialog icon:
A breakdown of the "Make Parameterized Phrase" dialog
- The text field takes plain text and the tokens of selected parameters.
- Click the [ + ] to open a drop tree of available parameters. Select from the list to generate a token in the text field.
- Valid parameters that are included in the phrase appear in the dialog table under the heading "Parameter".
- Some selections have format options. If options are available, they will appear in the dialog table under the heading "Options".
The drop tree includes parent and child parameters. For parameters related to date and time, child parameters display a portion of the parent.
For example, %[StartDate] will display the full start date (ex. yyyy-MM-dd) and %[StartDate.DayNum] will display just the day (ex. dd) portion of the start date.
The text field is fully editable. Type in plain characters at any time. Use copy, cut and paste to rearrange plain text and tokens. You do not need to use the selector to insert parameters, you can type out tokens. Hit tab or click OK and reopen the dialog to see the typed parameters appear in the dialog table. If you don't see the parameter you expect, the token may be wrong or mistyped.
When building a parameterized phrase, leave a space between each element unless you want words to run together. If building your own time format, it is up to you to include colons between hours, minutes, and seconds.
Parameterized Phrases with Custom Report Parameters
As described in Report Parameters, parameters that you create for your report can also be used in your parameterized phrases. After the Report Parameter has been added to the report, the option will appear in the Parameterized Phrase Selector.
Tag type report parameters include a selection of available data such as name, shortname, description and value.
Parameterized Phrase Selection
Header
The Header setting is found in a Data Set properties panel or Data Cell properties panel when an Available Data Field is selected. This may represent, as a common example, the label at the top of a column in a table.
Selector options will change depending on context. Different Data Set types feature different selections.
| ShortName | The name of a tag, excluding all parents. |
| DataColumn | The function applied to the column. |
| Field | For any I/O tag (including legacy input / output tags) this is simply "Value". FField is most useful when displaying driver statistics or values from custom tags that store data other than value |
| Units | Engineering units configured for the tag displayed in any column. |
| RelativeName | The name of a tag including parents to the selected Context or the top of the tag tree. |
| Description | The configured description of each tag. |
| AncestorShortName | The shortname of an ancestor tag at a specified level (default: 1). Ex. If tag = Station 1\Pump 1\Flow, Then AncestorShortName at Level 1 = "Pump 1" |
| AncestorRelativeName | The name of an ancestor tag at a specified level (default: 1) including parents to the selected Context or the top of the tag tree. Ex. If tag = Station 1\Pump 1\Flow, Then AncestorShortName at Level 1 = "Station 1\Pump 1" |
| AncestorDescription | The configured description of an ancestor tag specified by level (default: 1). |
AncestorShortName and AncestorRelativeName are handy in Pivot Tables.
Time Format
Time-related phrases are found in settings that display a date or time. For example, in a Tag Query, the Available Data Field, "Running Time" accepts a parameterized phrase for the setting "Format". These parameters are specific to time and date.
| Date | Date displayed as yyyy-MM-dd by default. |
| Date.DayNum | The dd portion of Date. |
| Date.MonthNum | The MM portion of Date. |
| Date.Year | The yyyy portion of Date |
| Date.DayString | The name of the day of the week. |
| Date.MonthString | The name of the month of the year. |
| Time | Time displayed as h:mm tt by default. (tt represents AM/PM) |
| Time.Hours12 | The current hour using a 12-hour clock. |
| Time.Hours24 | The current hour using a 24-hour clock. |
| Time.Minutes | Of the time expressed as hh:mm:ss, this is only the mm. |
| Time.Seconds | Of the time expressed as hh:mm:ss, this is only the ss. |
| Time.SubSeconds | Seconds with three decimal points of accuracy. |
| Time.AMPM | AM or PM |
Text Component Contents
Drag and drop a text component onto the canvas to find the parameterized phrase maker next to the field "Content". Custom Report Parameters will appear in the selector after they have been added to a report.
See Use Your Parameters in Report Text for more information.
Parent parameters:
| StartDate | Date the report was run, displayed as yyyy-MM-dd by default. |
| MonthString | The name of the month of the year. |
| EndDate | End date of the reporting period. |
| EndTime | End time of the reporting period. |
| RunDate | The date when the report was run. |
| RunTime | The time when the report was run. |
| WorkstationName | The name of the workstation from which the report was generated. |
| TimeZone | The time zone that the report was run in. |
Children of Data and Time parameters:
| DayNum | The day portion of the parent. (ex. dd becomes "02" for the 2nd.) |
| MonthNum | The month portion of the parent. (ex. MM becomes "06" for June.) |
| Year | The year portion of the parent. (ex. yyyy becomes 2026) |
| DayString | The day portion of the parent, represented as a string. (ex. Monday) |
| MonthString | The month portion of the parent, represented as a string (ex. May) |
| Hours12 | The hour portion of the parent, represented from a 12-hour clock. |
| Hours24 | The hour portion of the parent, represented from a 24-hour clock. |
| Minutes | Only the minute portion of the parent timestamp. (If the timestamp is 08:15:26, this value is 15.) |
| Seconds | Only the second portion of the parent timestamp. |
| SubSeconds | Seconds with three decimal points of accuracy. |
| AMPM | The morning or evening status of the parent timestamp. |
Custom Report parameters:
| Status | 1 or 0 for TRUE or FALSE. |
| Short | Numeric. 32-bit integer (+/- 32,767. No decimals.) |
| Long | Numeric. 64-bit integer. (+/- 2,147,483,648. No decimals) |
| Double | Numeric. 64-bit floating point (Can include decimals) |
| Text | String. |
| Duration | A length of time. Displays as a numeric multiplier and an initial representing a unit of time. Seconds (S), Minutes (M), Hours (H), Days (D), Weeks (W), Months (C), Years (Y), Quarters (Q), Single Value (V) |
| Tag | Linked to a tag. Expand the parameter to see the values that are available to display. For example, Tag.Name, Tag,Shortname, Tag.Description, Tag.Value. |
Available Data Field time format
These parameters are available in the following Format fields:
- Report Tag Query dataset --> Running Time data field
- Report Recipe Batches dataset --> Batch Duration and Step Duration data fields
(Each of the following examples is based off of a total run time of 326589.1234 seconds)
| TotalSecondsFullPrecision | Total running time, in seconds, to 4 decimal points. (ex. 326589.1234) |
| Milliseconds | The number of milliseconds in the run time value. (ex. 123) |
| TotalMilliseconds | Total running time in whole milliseconds. (ex. 326589123) |
| Seconds | The number of seconds in the run time value. (ex. 9) |
| TotalSeconds | Total running time in whole seconds. (ex. 326589) |
| Minutes | The number of minutes in the run time value (ex. 43) |
| TotalMinutes | Total running time converted to whole minutes. (ex. 5443) |
| Hours | The number of hours in the run time value. (ex. 18) |
| TotalHours | Total running time converted to whole hours. (ex. 90) |
| TotalsDays | Total running time converted to whole days. (ex. 3) |
Calculation Data Set Parameters
| Operation | Consolidate, Summarize or the math operation selected for this step. |
| OperationType | Only for Consolidate or Summarize, the data type (for example, Average, Totalize, Starts) |
| Data1SourceHeader | The header generated from the first source of data in the step. Invalid if the data source is a report parameter or a constant. |
| Data2SourceHeader | The header generated from the second source of data in the step. Only basic math operations have a second data source. Invalid if the data source is a report parameter or a constant. |
Recipe & Batch Data Set Parameters
| DataField | The name of the selected Available Data Field. (ex. "Recipe Name", "Step", "Batch Duration".) |
| Parameter | The name of the parameter. (ex. "Canola Oil", "Temperature", "Frying Time"). Available for Parameter fields only. |
| Unit | The unit specified in the Recipe Parameter tag. Available for Parameter fields only. |
Transaction Data Set Parameters
| DataField | The name of the selected Available Data Field. |
| Units | Valid only for Available Data Fields referencing an I/O & Calculations tag. The engineering unit specified by that tag. |
| Description | Valid only for Available Data Fields referencing an I/O & Calculations tag. The description specified by that tag. |
| LoggerShortname | The shortname of the Transaction Logger tag. |
Create Reports for Recipe & Batch Management
Create Transaction Logger Reports
