QPR Scripting enables easy access to the QPR API commands. Scripts are programs written in VBScript (Visual Basic) that can handle typical automated model administration tasks or integrate QPR Products with other applications. QPR Scripting utilizes standard Microsoft Windows Scripting capabilities with the addition of the QPR Application Object Model.
In the case you are not familiar with Visual Basic Scripting (VBScript), please see the language reference and User's Guide at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/vtoriVBScript.asp.
Scripts are extremely useful for automating certain model operations. You can, for example, define an XML export to be performed silently (i.e. no user interface is displayed) at a certain time, after which the data can be used in a third party tool. You can also create and update QPR Metrics models by using scripts.
When writing scripts for QPR products, the scripts must have <QPR_SCRIPT_FILE> as the very first line (header) of the file without any kinds of lines (including blank ones) preceding the QPR script header line. There are different options that can be added to the script header. See the Script Header Settings chapter for more information about the different settings. The scripts must be saved as *.qprmsc (QPR Metrics) and *.qprpsc (QPR Modeling Client) files.
To have the name and description of the script displayed in the Run Script menus in QPR Metrics client and QPR Modeling Client, use the following tags in the beginning of the script:
<NAME Name for the script>
<DESCRIPTION Description for the script>
The name and the description may not contain the '<' or '>' characters.
To have the script displayed as a a separate button in the Ribbon in QPR Metrics and QPR Modeling Client instead of under the Run Script menu, use the following tags in the beginning of the script:
<BUTTON_PLACE Name of the Ribbon tab where to place the button> - Mandatory. Tab name is matched according to the localized tab names of the selected user interface language at client startup. If a matching tab name isn't found, a new tab will be placed on the Ribbon. If not defined, script will be placed under the Run Script menu.
<BUTTON_GROUP Name of the group in the Ribbon tab where to place the button> - Optional. Default value is "Scripts".
<BUTTON_NAME Name of the button> - Mandatory.
<BUTTON_IMAGE Path to an image file to be used as the button image> - Optional. Supported image files are bmp, jpg, png, and gif. Default image is the same image used for the Run Script button.
To control the visibility of a script in the QPR Modeling Client’s Ribbon, use the following tag in the beginning of the script:
<MODEL_LC Model license code>
The model license code in the tag is always compared to license code of the currently open model. When a new model is created or an existing model loaded, QPR Modeling Client will check if there are script files with matching Model License Code reference in C:\ProgramData\QPR Software\QPR 2023\2023.1\Clients\pgscripts folder. The following rules apply:
•If the <MODEL_LC Model license code> tag is missing or the Model license code is empty, there's no special action, i.e. the script is shown and works normally.
•If the <MODEL_LC Model license code> tag exists in the script file, and the Model license code is defined, the Model license code is compared to the license code of the currently open model:
oIf there is no model loaded in QPR Modeling Client, the script isn't shown.
oIf the currently open model doesn't have a license code or the Model license code isn't found in license codes of the currently open model, the script isn't shown.
oIf the Model license code is found in license codes of the currently open model, the script is shown and it can be executed.
•Licensed scripts are always checked when a model is loaded or a new model is created.
•Licensed scripts can be executed when selected from file list i.e. from "More scripts...".
Note that it's recommended to save the script with UTF-8 encoding if you want to display the script in the separate button in the Ribbon. If the script file contains special characters, for example "ä" or "ö", the recommended encoding is UTF-8 BOM.
The scripts must always contain a "Sub Main" procedure, from which the script's execution is started. Both xxAplication and xxModel objects are initialized for scripts automatically.
The following chapters provide you with example scripts that you can use as a basis when building your own scripts. You can also find some example scripts in Appendix A.
