Recipes

Use a Recipe worksheet to load tag values from and/or save tag values to an external data file during project run time. It is typically used to execute process recipes that comprise many predefined settings, but you can also use it to take snapshots of the project state or store other types of data.

The external data file can be one of two file types: a standard .xml file or a space-separated .dat file. Each type of file has its own benefits and limitations. The .xml file stores the data in an easy-to-read XML format that can be processed by other programs or viewed in a web browser. (An .xsl file is saved and associated with the .xml file, and the web browser uses that .xsl file to style the data as a web page.) Furthermore, the .xml file can handle large arrays of values without issues. The tag names are saved with the tag values, however, so the values can only be loaded back into the same tags.

In contrast, the .dat file stores the tag values as raw data, without tag names. (An .rcp file that contains the recipe configuration is saved and associated with the .dat file.) That means you can configure one Recipe worksheet to save tag values to the file and then configure another Recipe worksheet to load the saved values into different tags. You must be careful about how the project tags are ordered in their respective worksheets, however, or else the worksheets will conflict with each other over how they parse the data. Furthermore, because of how the raw data is saved line-by-line, the .dat file cannot handle large arrays of values.

In both cases, the files for all recipes should located in the Web sub-folder of your project folder (for example, <project name>\Web\Recipes).

To create a new Recipe worksheet:

1. Do one of the following:

   • On the Insert tab of the ribbon, in the Task Worksheets group, click Recipe;

   • Right-click the Recipes folder in the Project Explorer, and then click Insert on the shortcut menu; or

   • Click New on the File menu, click the File tab, and then select Recipe Worksheet.

   A new Recipe worksheet is opened for editing in the Screen/Worksheet Editor.

   

2. In the Description box, type a description of the recipe.

   This is for documentation purposes only and does not affect the execution of the worksheet.

3. In the File Name box, type the name of the external file that will store the data. Do not include the file extension (.xml or .dat), because that will be automatically determined by whether the Save As XML option is selected. This field accepts String expressions (tag only).

4. In the Register Number box, type a tag to define the register number to be read from or written to a database file.

   Note: This setting is for legacy purposes only, and it should not be used in a new Recipe worksheet.

5. Select the Save As XML option to save the data to a standard .xml file, or clear the option to save the data to a space-separated .dat file.

   This option is selected by default.

6. Select the Unicode option to save the data in Unicode format (two bytes per character), or clear the option to save the data in ANSI format (one byte per character).

   This option is selected by default.

7. In the body of the worksheet, configure a row for each project tag that you want to include in the recipe:

   1. In the Tag Name column, type the name of the project tag.

      If the tag is an array, a class, or both, then all of its array elements and class members are included by default. To include only a specific element and/or member, type the full name including array position and/or member name (for example, MyArray[3].MyMember).

   2. In the Number of Elements column, type the number of elements that you want to include from the specified tag.

      This is starting from the array position that you specified in the Tag Name column, or from position 0 if you did not specify a position. You can type either a literal value (for example, 10) or the name of a project tag enclosed in curly brackets (for example, {MyNumberOfElements}), so that the number of elements can be programmatically changed during project run time.

8. When you are done, save and close the worksheet.

To execute a Recipe worksheet during project run time, call the Recipe function. Unless you are using an existing data file that has been copied from another project, you must call the function at least once to create a new data file and save the initial values of the included tags.