Use this dialog to define a variable command to be used in a Formattable Report.
From the top section of the commands list you can add a variable command. Variables are user named fields that have their values assigned during the running of the report. They can be used in a report for many purposes, including counts, remembering names, remembering the previous item’s fields, calculating largest sizes, passing parameters between reports, inputting user values, showing messages, showing progress and many more uses.
Editing a Variable Command
A variable is like a ‘memory’ that remembers a value for use later on. If you need to hold a value for calculation purposes, or to output to the report, you can use a variable to do this.
Command - This shows the description of the command as it appeared in the script before editing it.
Variable Name - All variables must be named. The drop-down list shows variables already defined in the report, you can also add new ones by typing in a unique name.
Variable Type - If the named Variable has not already been defined earlier in the format script you can set its type using one of the radio buttons shown. A Variable’s value must have a specific type, which helps in deciding how operations work on them. They can be one of: Integer (for Counts), Text, Numbers, Design Length (for holding Design Sizes), or boolean (true or false).
Actions
Several different operations or actions are available on these variables, defined using the Edit Variable Command dialog above. The following are different variable actions, performed when the variable command is reached when running the format script.
Set Value To
This action is usually used to introduce the variable and initialise its value before it is used, but can also be used to change the value layer in the script. The controls available for this action are shown in the dialog above. The value that you want to set the variable to can be supplied by one of the following methods:
- Fixed Value. e.g. an initial count of 1.
- From a design item’s field - Check the Field Contents box and select the field you want the value to be extracted from. The drop down list will contain fields that are relevant to the item type you are currently reporting within the script. So if the variable is being defined within a List Of Components command the fields will include component parameters, like its name. If Attribute is chosen the attribute controls are presented (as in the above example) for you to choose which attribute the value is to come from and which property of the attribute is to be used.
- From another variable - Check the Field Contents box and select “Variable” from the drop down list. A list of variable names will be presented in another drop down list. Select the name of the variable that you want to copy the value from.
- From the parent report - Check the Runtime Parameter box and specify the number of the parameter from the parent report you wish to copy the value from. This will only work at run time if your user report has been run from another report and it has set up the parameter you wish to copy.
- Multi Line Text. Only available if the variable type is Text.
Increment Value By
The current value is increased in size by adding another value obtained using the same methods as defined for Set Value To above. For example, choose this action to change the value of the variable each time round the list in which this command is placed. Not available for text or boolean variables.
Increment Text
The current text value is appended a number at the end (if not already present, number starts at 1) and is increased by 1. For example, choose this action to increment the value of a text variable each time round the list in which this command is placed. This operation is only available for text variables.
Decrement Value By
The current value is decreased in size by subtracting another value obtained using the same methods as defined for Set Value To above. Not available for text or boolean variables.
Append Value With
The current text value is appended with another text value obtained using the same methods as defined for Set Value To above. This operation is only available for text variables.
Multiply Value By
The current value is multiplied by another value obtained using the same methods as defined for Set Value To above. Not available for text or boolean variables.
Divide Value By
The current value is divided by another value obtained using the same methods as defined for Set Value To above. Not available for text or boolean variables.
Ask User for Value
When this command is run, a prompt dialog is displayed containing the Prompt text that you supply here to get a user value. The response will be placed into the variable.
Use the drop down list next to Prompt to choose the type of prompt text. Choose Fixed Value to directly type in the prompt text, or choose Variable to select the name of a variable that will be used at runtime to provide the prompt text.
You can offer a drop down list of possible values when prompting them for their input, e.g. a list of variant names in the design. To do this check the Show List of Values of Type box and choose a type of design item to present in a list when the prompt command is run. Names will be extracted at run time from the design (if there is a design and it is of the correct type).
There are two special value types. Choose
You can use a checkbox to specify whether to Allow Users Own Value or to only let them choose a value from the drop down list.
You can provide a ‘Browse’ button for users to select a directory by checking the box Folder Browser.
Set the Default Value with the text you want to present as the default answer. Use the drop down list next to Default Value to choose the type of default value. Choose Fixed Value to directly type in the default value, or choose Variable to select the name of a variable that will be used at runtime to provide the default value.
If the variable type is boolean the default button will be the Yes button unless you provide “false” as the default value. If the variable type is text, and a drop down list has been set up, and Allow Users Own Value is not checked, then you must make sure the Default Value matches one of the entries in the list, otherwise the first item in the list will be presented as the default answer.
Extract Field From
Use this to extract a field from the start of another variable. Using this command within a While loop enables you to split a string into fields and loop with a variable set to each field in turn. For example the first part of a report may build up a comma separated list of components in a text variable. Then the second part of the report could extract each component name in turn and report it.
Use the Extract Field from start of Variable drop down list to type or choose the name of the variable to extract the fields from, and provide the Field Separator string that is at the end of each field. When run a field will be removed from the start of the text variable and copied to our variable. If the Field can be Quoted box is checked, quotes will be removed from the field after extraction.
Replace Text In Value
Use this to replace a sequence of characters in a text string with a different sequence of characters. For example this could be used to replace spaces in part names (which old pick and place machines do not like) with another character before they are reported.
Use the drop down list next to Replace Text to choose the type of text you are going to replace. Choose Fixed Value to type in the text sequence to be replaced in the edit box, or choose Variable to select the name of a variable that will be used at runtime to provide the string to be replaced, or choose Whitespace to easily replace all spaces, tabs and newline characters.
Then use the drop down list next to With Text to choose the type of text to replace with. Choose Fixed Value to type in the text sequence to replace them with (leave this blank to simply remove them, i.e. replace them with nothing), or choose Variable to select the name of a variable that will be used at runtime to provide the text to replace with.
If the Replace All Occurrences box is left unchecked, only the first occurrence of the text will be replaced.
Substitute Environment Variables
Use this command to replace named operating system Environment Variables defined in the current variable with their value from the operating system. Environment variables are defined using their name delimited at both ends by the substitute character (normally this is % percent). Check the Substitute Character box to define your own specific character, or leave it unchecked to use the character defined in the General Options dialog.
Convert Text In Value
Use this to convert the text value defined in the current variable by a specified method. Methods available are Convert To Upper Case and Convert To Lower Case to change all characters in the text to the chosen case, Remove Whitespace At Start and Remove Whitespace At End to remove all spaces, tabs and newline characters from the start or end of the text.
Save To Report Result
Use this to save the current value of this variable as the report result. This is only relevant if the report has been run by a parent report using the Run Report command. The parent report can then retrieve this result and place it into its own result variable to use in its report.
Show Value In Message Box
When the report is run this command will display the current contents of the variable in a message box. The report output continues when the OK button is pressed.
Show Value In Progress Bar
When the report is run this command will display the current contents of the variable in the progress bar. Use this to indicate progress when the report takes a long time, for example to show the current library and part being reported in a library report for all libraries.
Write Value To Report
Writes the current value of the variable to the report.
New Column and Field Information - click here for Dialog details.
If the variable is of type “Number”, use the Number Format command to set the precision and decimal point character to be used in the report.
Related Topics
Report Maker | Generate Reports | Angles | Attributes | Set Alternate Attributes | Component Group List | Coordinates | Fixed Commands | If | List | List Field | Number Format | Position | Value | Variable | While