3. Overview Automation

When creating a number of equal reports it is recommended to automate this task.

3.1. Automation from the user’s point of view

The user chooses a category from the report menu, e.g. Map Plots. A list of available reports will be displayed. Example:

The user selects a report. The next step is to select data files. To do so the following dialog box will be displayed:

Depending on the automation script up to 16 data files can be selected.

A template will be opened and the data will be loaded into the diagrams. The header data will be inserted into the template. The creation of the page finishes when a dialog box appears for the input of additional text data. The following dialog box is used for this:

3.2. Creating an automation

An automation consists of two files:

• The IC file (script file) contains the program which will control the execution of the automation. The script file should have the file name extension .ic.
• The IPW file (UniPlot document) contains the template with diagrams, text fields logos etc. The UniPlot document should have the file name extension .ipw.

The IC and the IPW file should be saved in the same directory. To install the automation, the directory where the two files are stored must be specified in the Tools=>More Options dialog box, in the field Search path for automation script files (e.g. C:/UNIPLOT/SAMPLES/AUTOMATE/). Multiple directories can be specified and must be separated by a semi-colon (;). After the dialog box is closed all IC files in the specified directories will be loaded.

3.3. The template file (.IPW)

The template is a ordinary UniPlot document containing diagrams, text and drawing objects, logos, OLE objects and all other possible UniPlot objects. The template is created normally using UniPlot.

3.4. Template

The scaling of the diagram axes should be setup in the template so that the diagrams display the interesting part of the data. If the data varies significantly the axis can be autoscaled in the script file. x and y axes can be scaled independently (see auto_ScaleAxes). Each diagram on a page has an unique name. The name will be used in the script file to access a diagram and to add data to a diagram.

Every page can have one legend. The legend is a normal text object. (To create a text object select the button A from the toolbar and drag the mouse). The text of the text object must be $LEGEND$.

The template can contain field functions. By using field functions multiple legends can be created (see Field Functions) for a page. To create a legend for a specific diagram, add a text object to the diagram and type in the text @f{legend}.

To create a field function that displays the document name, create a text element and type the text @f{documentname} into the element.

3.5. Place-Holders

The template can contain any number of text place-holders which will be replaced during the execution of an automation script by user input or by text received from the data file. The place-holder is text that begins with a dollar sign, followed by the text, followed by another dollar sign. Example: $Engine$.

To set an order to display the place-holder text in the dialog box an optional number can be added to the place-holder. Example: $(1)Title$. The number must be surrounded by brackets and must placed behind the first dollar sign.

If the text of a place-holder should be received from a data file the spelling and case must be identical to one global attribute in the NC file. Normally every NC file created by UniPlot has a global attribute “Origin” containing the file name of the original data file. The place holder text for this attribute will be $Origin$. To read the attribute value of a variable the variable name must be followed by a period followed by the name of the attribute. Example: $Torque.long_name$

A template file can contain multiple pages. Which page is loaded and in what order will be specified in the IC-file.

3.6. Style file

The current style file will be unloaded at the beginning of an execution of an automation to avoid unwanted scaling and filtering of datasets created with auto_LoadDataset. When the execution is finished the unloaded style file will be reloaded.

To use a style file in an automation it must be loaded using the auto_LoadStyleFile function.

If a style file is loaded the style will be copied to the dataset. For each diagram a counter is used to select the style for a dataset. The first dataset added to the diagram will use the curve style with index 1. The second dataset will use curve style 2 and so on. To modify the counter for a diagram

call auto_SetDatasetStyle.

Examples for other functions to set the curve style: auto_xy_SetStyle, auto_xy_SetStyleAttribs, XYSetProps.

Example:

hData = auto_LoadDataset("Diagram1", "rpm", "torque");
if (hData) {
    auto_xy_SetStyle(hData, "2D Red"); // Style should be available in the current style file.
}

or:

hData = auto_LoadDataset("Diagram1", "rpm", "torque");
if (hData) {
    // solid line with width 4 in red
    auto_xy_SetStyleAttribs(hData, "Line", [0, 4, 255, 0, 0]);
    // use akima spline
    XYSetProps(hData, "filter-functions-on='1' filter-functions='akimaspline'");
}

3.7. The IC file

The script file (.ic) is a text file that contains a program which controls the execution of the automation. To create a script file open a program editor (File=>New). To edit an existing script file choose File=>Open.

The following examples are used to describe the different sections of an automation script file. The examples can be found in the directory UNIPLOT\SAMPLES\AUTOMATE.

To enable UniPlot to execute the following examples load the automation scripts into UniPlot. Choose Tools=>More Options. In the following dialog box type in the path of the IC file in the text field Search Path for Automation Script Files (e.g. :file:`c:/uniplot/samples/automate/). Click the OK button. A new Reports menu should be added to the main menu.

Select the category Examples=>Example 1. In the data file dialog box that appears, select the example file map-data.xls.

Example

auto_AddToUI("Examples", "Example 1: Map", "RS_Example1");

def RS_Example1()
{
    MessageBox("In the following dialog please select the file map-data.xls");
    auto_SetFileNameDialogInit("*.xls", GetRootDirectory() + "samples/");
    svFile = auto_GetFileNameDialog(1);
    if (svFile[1] == "DLG_CANCEL") {
        return;
    }
    auto_LoadTemplate(GetRootDirectory() + "samples/automate/Example.ipw");
    auto_ImportData(svFile[1]);
    auto_LoadDataset("Diagramm 1", "N", "EWGMOM", "EWGLST");
    auto_LoadDataset("Diagramm 2", "N", "EWGMOM", "BEEWG");
    auto_ScaleAxes();
    auto_UpdatePage();
}

The function RS_Example1 controls the execution of the automation. This function is called when the user selects the respective menu.

To enable the user to call this function, the function call auto_AddToUI (UI for User-Interface) inserts a new menu item (“Examples”) to the Reports menu if this menu item is not already available and adds a new item to the listbox (“Example 1: Map”) that will be displayed when the user selects the menu item.

Then the script function RS_Example1 will be registered so that Reports=>Examples=>Example 1: Map can be called from the menu.

The function has three parameters:

auto_AddToUI(ssCategorie, ssDescription, ssFunctionName)

For each automation the auto_AddToUI function will be called up once.

The first parameter sets the name of the menu to which the evaluation should be assigned.

The function’s second parameter (“Example 1: Map”) will appear in the dialog box when the Evaluation=>Example-Evaluation menu is chosen.

The third parameter (“RS_Example1”) is the name of the function that is to be called up. The name can be chosen freely. Because each function name in UniScript can only be used once, make sure the name does not already exist. It is recommended to start the name with a prefix that is not already in use by UniPlot e.g. RS_ or ABC_ etc.

With the help of the what function, it is possible to check if functions with the prefix already exist in UniPlot. To do this, open the command window and enter, for example, what("RSB_*"). A list will appear with all the functions that begin with RSB_. The script file should be saved with a template file in the same directory. For example: UNIPLOT\TEMPLATE\AUTO.

The automations can be located in various directories. The search directory is set in the Tools=>More Options dialog box. Search directories are entered in the Search Path for automation script files. The paths must be separated by a semi-colon (;). There should only script files for automation saved in these directories.

When starting UniPlot, the script files will be searched and opened in the paths given. The script files must have the name extension .IC.

Within a script function, all UniScript functions can be called up. To simplify the writing of script files, prepared functions are available for standard functions such as Choose Files, Search and Replace Text, and for the calculation of data.

These functions are briefly described here:

auto_GetFileNameDialog()

The user can choose data files with this function. The function returns the name of the chosen file as a vector. If the Cancel button is chosen the character string “DLG_CANCEL” will be returned as the first element of the vector. If more than 4 files should be chosen, the number is entered in the function as the first parameter. For example, calling auto_GetFileNameDialog(8) gives the user the possibility to choose up to 8 files. A maximum of 16 files can be chosen.

auto_ReplaceTextDialog()

This function searches the template page for text matching the place holder pattern ($Text$). If the text is found in the template page, a dialog box will appear. With its help, the text can be entered. If a NC file name (return value of the auto_ImportData function is entered, the function tries to find the place-holder text in the global attributes or the variable attributes of the NC file. All of the loaded text from the NC file will be marked with an asterix in the dialog box.

auto_LoadTemplate()

This function opens a template and creates a copy of the required page. The copied page will be inserted into either a new document or in the active document.

The first parameter is the name of the template. If the template is in one of the entered automation script directories, the path should not be entered.

The second parameter is the name of the page. If the page is to be inserted to the active document, the auto_AddPage function should be called first. (See Example RS_Example4.

The function returns the handle of the created page. The handle can be used, for example, to receive the handle of a diagram (PageGetLayerHandle).

Instead of loading a page using auto_LoadTemplate a page can be prepared to use the “auto_*” functions by calling auto_SetTemplate.

auto_ImportData()

This function opens the given data file and converts it to NC format. The file name will is given as the first parameter. The name of the NC file will be returned as a return value. The NC file name can be used, for example, for the auto_ReplaceTextDialog function.

The name of the created NC file will be saved in a global variable. The auto_LoadDataset function uses this variable to load data from the NC file to a given diagram.

auto_LoadDataset()

The auto_LoadDataset function creates an 1D, 2D or 3D dataset. The dataset will be inserted into the given diagram. The function returns a handle which will be used to access a created dataset.

The dataset style will be taken from the active style file. The first dataset in the diagram receives the first style from the file, the second dataset receives the second style in the file and so on.

To set the style for the next dataset being created by auto_LoadDataset call the auto_SetDatasetStyle function. The style can be passed by name or index, e.g. `` auto_SetDatasetStyle(2)`` or auto_SetDatasetStyle("2D Solid").

auto_UpdatePage()

This function should be called in order to finish the creation of a page.

Example

Create a map with a color legend

auto_AddToUI("Examples", "Example 2: Map with legend", "RS_Example2");

def RS_Example2()
{
    MessageBox("In the following dialog please select the file map-data.xls");

    auto_SetFileNameDialogInit("*.xls", GetRootDirectory() + "samples/");
    svFile = auto_GetFileNameDialog(1);
    if (svFile[1] == "DLG_CANCEL") {
        return;
    }
    auto_LoadStyleFile(GetRootDirectory() + "samples/automate/style1.icb");
    hPage = auto_LoadTemplate(GetRootDirectory() + "samples/automate/Example.ipw");
    auto_ImportData(svFile[1]);
    hData = auto_LoadDataset("Diagramm 1", "N", "EWGMOM", "EWGLST");
    auto_xyz_CreateColorLegend(hData)
    auto_LoadDataset("Diagramm 2", "N", "EWGMOM", "BEEWG");
    auto_ReplaceText("$X-Title$", "Dies ist die Y-Achse");
    auto_ReplaceTextDialog()
    auto_UpdatePage();
}

In the following example, up to 3 data files can be chosen:

auto_AddToUI("Examples", "Example 3: WOT 1", "RS_Example3");
def RS_Example3()
{
    MessageBox("In the following dialog please select the file VOLLAST.ASC");
    auto_SetFileNameDialogInit("*.asc; *.nc", GetRootDirectory() + "samples/");
    svFile = auto_GetFileNameDialog(3);
    if (svFile[1] == "DLG_CANCEL") {
        return;
    }
    NumberOfFiles = len(svFile);
    hPage = auto_LoadTemplate("example");
    for (i in 1:NumberOfFiles) {
        svFile[i] = auto_ImportData(svFile[i]);
        auto_LoadDataset("Diagramm 1", "N", "MEFF");
        auto_LoadDataset("Diagramm 2", "N", "EWGLST");
    }
    auto_ScaleAxes();
    auto_ReplaceTextDialog(svFile[1]);
    auto_UpdatePage();
}

The following example creates a document with 2 pages. The first page shows the data (N, MEFF) und (N, EWGLST) and the second page displays the data (N, BEFF) und (N, TOEL1)

auto_AddToUI("Examples", "Example 4: WOT 2", "RS_Example4");

def RS_Example4()
{
    MessageBox("In the following dialog please select the file VOLLAST.ASC");
    auto_SetFileNameDialogInit("*.asc; *.nc", GetRootDirectory() + "samples/");
    svFile = auto_GetFileNameDialog(3);
    if (svFile[1] == "DLG_CANCEL") {
        return;
    }
    NumberOfFiles = len(svFile);

    hPage = auto_LoadTemplate("example");

    for (i in 1:NumberOfFiles) {
        svFile[i] = auto_ImportData(svFile[i]);
        auto_LoadDataset("Diagramm 1", "N", "MEFF");
        auto_LoadDataset("Diagramm 2", "N", "EWGLST");
    }
    auto_ScaleAxes();
    auto_ReplaceTextDialog(hPage, svFile[1]);
    auto_UpdatePage();

    // Add the next page to the active Page
    auto_AddPage();

    hPage = auto_LoadTemplate("example");

    for (i in 1:NumberOfFiles) {
        svFile[i] = auto_ImportData(svFile[i]);
        auto_LoadDataset("Diagramm 1", "N", "BEFF");
        auto_LoadDataset("Diagramm 2", "N", "TOEL1");
    }
    auto_ScaleAxes();
    auto_ReplaceTextDialog(hPage, svFile[1]);
    auto_UpdatePage();
}

The following example shows how the average value of two curves can be calculated and how two datasets can be divided

auto_AddToUI("Examples", "Example 5: WOT with calculations", "RS_Example5");

def RS_Example5()
{
    MessageBox("In the following dialog please select the file VOLLAST.ASC");
    auto_SetFileNameDialogInit("*.asc; *.nc", GetRootDirectory() + "samples/");
    svFile = auto_GetFileNameDialog(2);
    if (svFile[1] == "DLG_CANCEL") {
        return;
    }
    NumberOfFiles = len(svFile);
    if (NumberOfFiles != 2) {
        MessageBox("Es müssen 2 Dateien ausgewählt werden");
        return FALSE;
    }

    hPage = auto_LoadTemplate("example");

    svFile[1] = auto_ImportData(svFile[1]);
    hData1 = auto_LoadDataset("Diagramm 1", "N", "MEFF");

    svFile[2] = auto_ImportData(svFile[2]);
    hData2 = auto_LoadDataset("Diagramm 1", "N", "MEFF");

    // Retrieve the handel of Diagramm 2
    hLayer2 = PageGetLayerHandle(hPage, "Diagramm 2");

    // Calculate Mean dataset
    auto_xy_Mean(hData1, hData2);

    // Calculate Div dataset and add to "Diagramm 2".
    auto_xy_Div([hData1, hLayer2], hData2);

    // Autoscale axes
    auto_ScaleAxes();
    auto_ReplaceTextDialog(hPage, svFile[1]);
    auto_UpdatePage();
}

The function auto_xy_Mean calculates the average of 2 datasets (curves). The datasets must have ascending x-coordinates and overlap in x-direction. The x-coordinates of the two datasets do not have to be identical.

Datasets will be passed to the function with their handles. Handles are returned from the function auto_LoadDataset.

The auto_xy_Mean function, like the auto_LoadDataset function, returns the handle of the created dataset. If the dataset cannot be created, the function returns the value 0.

To delete a dataset from a diagram, call up the XYDestroy or XYZDestroy function.

	Functions
auto_AddToUI	auto_AddToUI adds a UniScript function to UniPlot’s user interface. The function will be added to the Report Menu to the specified category.
auto_CloseDocument	auto_CloseDocument closes the active document. If the document was not saved with the auto_SaveDocumentAs function, it will close without being saved.
auto_AddPage	auto_AddPage adds a new page to the document.
auto_GetFileNameDialog	auto_GetFileNameDialog displays a dialog box which can be used to select up to 16 file names. The function can be used within an automation script.
auto_ImportData	auto_ImportData opens a data file and converts it to a netCDF file (.NC). The netCDF file is saved in the directory of the source data file or in the directory specified in toolsmore options dialog. The function can be used to import data from all supported file formats (ASCII-, Excel-, netCDF-Files etc.). For Excel files, the table name can be specified as the second parameter.
auto_LoadDataset	auto_LoadDataset loads a 1D, 2D, or 3D dataset from a data file opened with the function auto_ImportData.
auto_LoadStyleFile	auto_LoadStyleFile loads a style file. The style file contains descriptions which specify the style of a dataset. Some example files can be found in the the UniPlot Sample directory. They have the file name extension .sty .icb.
auto_LoadTemplate	auto_LoadTemplate opens a template.
auto_PrintDocument	The auto_PrintDocument function prints the entire document to the active printer.
auto_PrintPage	auto_PrintPage prints the page created with the auto_LoadTemplate function to the active printer.
auto_ReadNCText	auto_ReadNCText reads an attribute from the most recently imported data file.
auto_ReplaceText	auto_ReplaceText executes a find and replace command. The function searches in text objects and axis titles for the find text and replaces it with the specified text.
auto_ReplaceTextDialog	auto_ReplaceTextDialog can be used within an automation script to show a text dialog box.
auto_ReplaceTextFromNCFile	auto_ReplaceTextFromNCFile searches the given page for bookmarks (strings enclosed in dollar signs, Example $Origin$) and replaces the text with attribute values from the given netCDF (.NC) file.
auto_SaveDocumentAs	auto_SaveDocumentAs saves the document created with the auto_LoadTemplate function under a new name.
auto_ScaleAxes	auto_ScaleAxes re-scales all diagrams on the page created with the auto_LoadTemplate function, so that all datasets on the diagrams are completely visible.
auto_SetDatasetStyle	auto_SetDatasetStyle sets the dataset style for the next dataset to be created with the auto_LoadDataset function.
auto_SetLegendText	auto_SetLegendText creates a legend entry for 1D and 2D datasets. If the function is called without parameters, the file name from the loaded data will be used as text.
auto_UpdatePage	auto_UpdatePage should be the last function called to finish the template page. The function copies the created legend text in the text object with the $LEGEND$ place-holder, updates legend size, and updates the page on the monitor.
auto_UpdateLegendSize	auto_UpdateLegendSize updates the size of the legend, already set in the template with the $LEGEND$ bookmark, to the size of the legend text.
XLSREPORT_CreateFromTemplate	XLSREPORT_CreateFromTemplate inserts data into an MS-Excel template.

	Functions for x/y Datasets (1D and 2D Dataset)
auto_xy_Add	auto_xy_Add creates a new dataset from the sum of the y-coordinates of 2D datasets.
auto_xy_Correlate	auto_xy_Correlate creates a new dataset by using the interpolated y-coordinates of the first dataset as x-values and the y-coordinates of the second datset as y-values.
auto_xy_CorrelationCoefficient	auto_xy_CorrelationCoefficient calculates the correlation coefficient.
auto_xy_CreateDataset	auto_xy_CreateDataset creates a new 2D dataset.
auto_xy_CreateRegion	auto_xy_CreateRegion creates a new dataset by concatenating two datasets. The second dataset will be added to the first dataset in reverse order.
auto_xy_Derivative	Diese Funktion ist veraltet. Neue Scripte sollten die Funktion XYSetFilterFunctions verwenden.
auto_xy_Div	Creates a new dataset by adding the y-coordinates of the given 2D datasets.
auto_xy_Envelope	auto_xy_Envelope creates an upper or lower envelope (hull, boundary).
auto_xy_ExtractRange	The function is obsolete. New scripts should use the XYSetFilterFunctions function.
auto_xy_GetParentHandle	auto_xy_GetParentHandle returns the handle of the diagram hLayer, page hPage and document hDoc in which the dataset is located.
auto_xy_Integral	The function is obsolete. New scripts should use the XYSetFilterFunctions function.
auto_xy_IntegralValue	auto_xy_IntegralValue returns the integral value of the given dataset as a string.
auto_xy_Interpolate	The function is obsolete. New scripts should use the XYSetFilterFunctions function.
auto_xy_LabelDataPoints	auto_xy_LabelDataPoints labels the data points of a 1D or 2D dataset with its y value. If the dataset contains more than 50 data points, 50 labels will be distributed evenly over the data points.
auto_xy_LabelDataPoints_SetOptions	auto_xy_LabelDataPoints_SetOptions
auto_xy_LabelDataset	auto_xy_LabelDataset labels the first or last point of a 2D dataset with its name.
auto_xy_LinearInterpolation	The function is obsolete. New scripts should use the XYSetFilterFunctions function.
auto_xy_Max	auto_xy_Max creates a new dataset from the maximum values of the y coordinates of the given 2D datasets.
auto_xy_Mean	Creates a new dataset from the mean values of the y coordinates of the given 2D datasets.
auto_xy_MinMaxValue	auto_xy_MinMaxValue returns a string with the minimum and maximum value (y-coordinates) of the specified dataset.
auto_xy_Mult	auto_xy_Mult creates a new dataset by multiplying the y-coordinates of the given 2D datasets.
auto_xy_OneDown	auto_xy_OneDown moves the specified dataset one position down in the drawing order.
auto_xy_OneUp	auto_xy_OneUp moves the specified dataset one position up in the drawing order.
auto_xy_RemoveDoublePoints	The function is obsolete. New scripts should use the XYSetFilterFunctions function.
auto_xy_Scale	The function is obsolete. New scripts should use the XYSetFilterFunctions function.
auto_xy_SetStyleAttribs	auto_xy_SetStyleAttribs sets the line and/or marker style, color, etc. without using the style file.
auto_xy_Smooth	The function is obsolete. New scripts should use the XYSetFilterFunctions function.
auto_xy_SortX	The function is obsolete. New scripts should use the XYSetFilterFunctions function.
auto_xy_Spline	The function is obsolete. New scripts should use the XYSetFilterFunctions function.
auto_xy_Statistic	auto_xy_Statistic calculates some statistical values and returns them as a string.
auto_xy_Step	The function is obsolete. New scripts should use the XYSetFilterFunctions function.
auto_xy_Sub	auto_xy_Sub creates a new dataset by subtracting the y coordinates of the given 2D datasets.
auto_xy_histogram	Creates a histogram for the given 2D dataset.

	Functions for x/y/z Datasets (3D Datasets)
auto_xyz_Add	auto_xyz_Add creates a new dataset by adding the z-coordinates of the given 3D datasets.
auto_xyz_CreateColorLegend	auto_xyz_CreateColorLegend creates a color legend for the given 3D dataset.
auto_xyz_CreateHull	auto_xyz_CreateHull calculates a non convex data hull (Full Load Line, WOT) for the given 3D dataset if the data was measured at approx. constant x- (e.g. speed) or y-values.
auto_xyz_CreateIsolines	auto_xyz_CreateIsolines creates isolines for a 3D dataset.
auto_xyz_CreatePowermap	auto_xyz_CreatePowermap creates a power map (power hyperbola).
auto_xyz_Div	auto_xyz_Div creates a new dataset by dividing the z coordinates of the given 3D datasets.
auto_xyz_Interpolate	auto_xyz_Interpolate calculates a new interpolation matrix for the given 3D dataset.
auto_xyz_Mean	auto_xyz_Mean creates a new dataset by calculating the mean value of the z coordinates of the given 3D datasets.
auto_xyz_Mult	auto_xyz_Mult creates a new dataset by multiplying the z coordinates of the given 3D datasets.
auto_xyz_RelDiv	auto_xyz_RelDiv creates a new dataset by calculating the relative distribution value of the z coordinates of the given 3D datasets.
auto_xyz_SetIsolineStyle	auto_xyz_SetIsolineStyle sets the line style for all Isolines of a 3D dataset to the specified style.
auto_xyz_Statistic	auto_xyz_Statistic creates a text element with some statistical information for the given 3D dataset.
auto_xyz_Sub	auto_xyz_Sub creates a new dataset by subtracting the z coordinates of the given 3D datasets.

_id-1891577