Variables and functions are related features that allow you to use dynamic content (content that gets calculated when a report is executed) in parameters, file names, and other text in your report processing settings. For example, using variables and functions you can:
Report Commander version 1 had a similar but much more limited capability called dynamic file names and parameters. Dynamic text from the old version will be converted to the new format automatically. See the Variable Syntax Changes from Version 1 topic for more information.
Variables and functions are supported throughout Report Commander in most place where you need to enter parameters, file names, or other text. Wherever you see a text entry box in the Project Editor that has a {} button next to it, this indicates that the field supports variables and functions. When you click the button, the Text Edit window opens. This window provides a list of available variables and functions, and includes tools to help you insert them into your text using the correct syntax.
Variables allow you to insert predefined text into parameters, file names, and other text boxes in Report Commander.
Suppose that on one computer where you use Report Commander, all the report files are located in the folder "c:\reports". But you also want to be able to execute your projects on a second computer, which reads the reports over the network using the UNC path "\\mycomputer\reports". To avoid having to change the report path for your projects when you move them from one computer to the other, you can define a variable named "ReportPath" and set it to "c:\reports" on the first computer, and "\\mycomputer\reports" on the second. Then, in all your projects, you use the "ReportPath" variable when specifying the report name, instead of writing in the fixed path.
To do this, you open the Project Properties for one of your projects and go to the Variables tab. Here you add a User Variable named "ReportPath" with the value c:\reports. (A "user" variable means that it is available to all projects you work with on the computer, so you only have to define this variable once.)
Then, in the Report Properties where you specify the report filename, instead of entering c:\reports\report1.rpt, you enter ${ReportPath}\report1.rpt. When you execute the project, Report Commander replaces "${ReportPath}" with the value of the ReportPath variable.
Now on the second computer, you define the same User Variable called "ReportPath", but you set it to \\mycomputer\reports, and when the project is run on that computer, Report Commander will use that value instead.
You might also want to define variables for other values that need to be standardized, or that you want to be able to change easily if the project is run on a different computer. For example, you could define a "CompanyName" variable to make it easy to insert the company name in e-mail messages. Or an "OutputPath" variable to standardize where export files get written.
Report Commander supports four kinds of variables:
In the Project Editor, user and project variables are managed on the Variables tab of the Project Properties panel. The Command Line Builder does not support project-level variables, but you can manage user variables through the User Settings window.
When you execute a project using the Project Runner, you can set or override variable values from the command line.
Variables can contain other variables. For example, you can define the "ReportDrive" as c: and the "ReportPath" as ${ReportDrive}\reports. At runtime, the ReportPath variable will be expanded to c:\reports.
Variables can also include function calls. See the Variables with Functions topic for an example of defining a variable that includes function calls.
Report Commander automatically defines some variables for you, which can be used throughout your Project.
| Name | Description |
|---|---|
| now | The current date/time, in the form "yyyy-MM-dd HH:mm:ss". To specify a format, or calculate an offset from the current date/time, use the now function instead. |
| Project.Name | The name of the project (without the path or file extension) |
| Project.FileName | The complete path and filename of the project file |
| Project.Path | The path where the project file is located |
| Report.Name | The name of the report (without the path or file extension) |
| Report.FileName | The complete path and file name of the report |
| Report.Path | The complete path and file name of the report |
| Group.Name | The name of the Output Group |
| Group.FullName | The full name of the Output Group (includes the name of the Report) |
| Output.Name | The name of the Output |
| Output.FullName | The full name of the Output (includes the name of the Report and Output Group) |
| Output.n.PathAndFileName |
The complete file name (including path) of the export file produced by File Output (export) operation number n, where n is the "ID Code" shown on the properties page for the output. When you are exporting a report using the Command Runner, the ID will always be "1".
For example, in an e-mail message task you want to insert the file name created by your export. You can't hard-code the file name in the message because it's generated dynamically based on the date. Instead you can insert the variable token ${Output.1.PathAndFileName} to insert the name at runtime. |
| Output.n.FileName | The file name (without path) of the export file produced by File Output (export) operation number n. |
| Output.n.Path | The path (without file name) of the export file produced by File Output (export) operation number n. |
| Parameters.ParameterName |
The value of the ParameterName parameter at runtime. A variable is defined for each report parameter. For example, if your report has a parameter named "SalesRegion", you can use ${Parameters.SalesRegion} to insert the value of the parameter. Note: Any characters other than a-z, 0-9, "-", "_", and "." are removed from the parameter name when constructing the variable name. For example, of your parameter name is "Customer Record #", the variable would be named "Parameters.CustomerRecord". |
While variables allow you to easily insert predefined text, functions allow you to insert the results of calculations (similar to using formulas when designing a report).
For example, suppose that each morning you run a report and want that report to return data from the previous day, so you need to pass the previous day's date as a parameter to the report. You don't want to edit your Project each day to change the value of that parameter, so instead you can use a function to calculate the correct date for you: the now function allows you to insert a date calculated based on the current date when the report runs.
So instead of setting the report parameter to the date of 2015-01-23 and changing the value each time you run the report, you could set the parameter to @now("yyyy-MM-dd",-1,"day"). This tells Report Commander to take the current date/time, subtract 1 day, and format the resulting date in year-month-day format.
See the Function Reference for more information on the available functions.
User-defined functions are not currently available in Report Commander.
Related Topics
Reference