The marker functions in DIAL open DiveLine Markers, modify selections for their contents, and save them.
marker.find_succeeded(model)
Returns a Boolean value indicating whether the find function succeeded for the bottom-most window in the specified Marker. This function detects empty finds in a Marker. If the bottom window fails to open, a warning of "no records selected" is returned, along with a 0 value. Note that Map Markers are not supported.
marker.open(model, marker_name)
Opens a Marker with the DiveLine name marker_name (enclosed in quotation marks) from the DiveLine server, and assigns the cBase, Model, or DivePlan associated with the Marker to the Model specified in the special Object Variable model. A connection must be established to the DiveLine Server before the Model can be opened. If the Marker cannot be opened, the DIAL script ends.
marker.open(model, marker_name, dive_keys, dive_values)
For use with key and value arrays, opens a Marker with the DiveLine name marker_name (enclosed in quotation marks) from the DiveLine server. Assigns the cBase, Model, or DivePlan associated with the Marker to the Model specified in the special Object Variable model. Uses the dive_keys and dive_values arrays to populate QuickView values.
See
marker.print_window(model, options, printer, page_range)
Prints the bottom-most window of the specified Marker. However, any header and footer text in the Marker is not printed. Any basic window type is supported. The options argument is a comma-separated list of options. The optional printer argument can be set to "default", or to the name of a printer resource.
For example:
"/<hostname>/<some printer>".
The printer must be the third argument. Use "" if you have no options to specify. The page range is optional and includes a comma-separated list of pages and page ranges, such as "2,5-8,15,16-". Supported options include:
| copies=X | Prints X number copies of the window contents. |
| media=X | Specifies the page size to use ("letter", "a3", "a4", "a5", "legal"). |
| landscape | Prints in landscape mode, overriding the window's default. |
| portrait | Prints in portrait mode, overriding the window's default. |
marker.set_group(model, dim_name, group)
Sets the Dimension Values for dim_name in the Model specified in the special Object Variable model to be the values stored in the Group specified in the special Object Variable group. The Dimension must correspond to a simple single-Dimension table in the Marker. If values in the Group are not found in the specified Model, they are ignored.
marker.save(marker, marker_name)
Saves the Marker specified in the Marker special Object Variable marker to the DiveLine server as marker_name. This Marker includes any changed Dimension Values set by marker.set_group().
marker.save_report(model, filename, options)
Saves a static copy of the bottom-most report window specified in the Model special object variable model as a pdf or html file named filename (enclosed in quotation marks). Running DIAL manually saves the file to the local system; running DIAL through Workbench or a scheduled Production script saves the file to the current working directory (dl-dataroot\temp). When using DIAL scripts with Production, make sure that each generated report has a unique file name, especially as part of a walk statement.
The options argument is a comma-separated list (enclosed in quotation marks) that specifies the file type to create and any additional options. Supported options include:
| html | Saves the report as an html report. If the bottom-most window is a simple tabular, creates a default html report. |
| Saves the report as a pdf document. If the bottom-most window is a simple tabular, creates a default pdf report. | |
| xls | Saves the report as a Microsoft Excel xls document. If the bottom-most window is a simple tabular, creates a default Microsoft Excel report. |
| xlsx | Saves the report as a Microsoft Excel xlsx document. If the bottom-most window is a simple tabular, creates a default Microsoft Excel report. |
| embed_fonts=<true|false> | Indicates whether to embed font data into a pdf file. True embeds font data; false does not embed font data (default). True increases the file size but potentially eliminates fonts issues when using the pdf reader. False reduces the file size but might cause font issues. |
| width=<number> | Specifies the page width for a report. |
| height=<number> | Specifies the page height for a report. |
marker.save_text(model, filename, options)
Saves a static copy of the bottom-most window open in the Model specified in the special Object Variable model, as a text file named filename (enclosed in quotation marks). Running DIAL manually saves the file to the local system; running DIAL through Workbench or a scheduled Production script saves the file to the current working directory (dl-dataroot\temp).
The options argument is a comma-separated list of options (enclosed in quotation marks) specifying the type of text file to create. Supported options include:
| delim=tab | Sets the output delimiter to be a ASCII tab. |
| delim=comma | Sets output delimiter to be a comma. |
| delim=<character> | Sets the output delimiter to the specified character. |
| include_totals | Includes the totals row in the output. |
marker.save_window(model, filename, options, map_template)
Saves a static copy of the bottom-most window of the specified Model (model) as a file (filename) enclosed in quotation marks. Running DIAL manually saves the file to the local system; running DIAL through Workbench or a scheduled Production script saves the file to the current working directory (dl-dataroot\temp). Any basic window type is supported as well as the file types listed in the following table.
The options argument is a comma-separated list (enclosed in quotation marks) that specifies the file type to create and any additional format options. Supported options include:
| txt | Saves the window as a text file. Does not work with charts or plots. The window must be a Tabular or a Report. |
| csv | Saves the window as a csv file (comma-separated values). Does not work with pie charts, plots, scatter charts, or stack plots. |
| xml | Saves the window as an XML version 1.0 file using UTF-8 encoding. |
| html | Saves the window as an html file. Does not work with pie charts, plots, scatter charts, or stack plots. |
| Saves the window as a pdf document. Works with any window type. | |
| jpeg | Saves the window as a jpeg image. Works with any window type. To ensure the image is fully displayed, specify the width of the image by using the width attribute. |
| png | Saves the window as a png image. Works with any window type. To ensure the image is fully displayed, specify the width the of image by using the width attribute. |
| xls | Saves the window as an xls file. |
| xlsx | Saves the window as an xlsx file. |
|
width=<number> |
Specifies the page width for a text output report, or the image width in pixels for jpeg and png images. Text files are divided into logical pages. |
| height=<number> | Specifies the page height for a text output report, or the image height in pixels for jpeg and png images. Text files are divided into logical pages. |
| embed_fonts=<true|false> | Indicates whether to embed font data into a pdf file. True embeds font data; false does not embed font data (default). True increases the file size but potentially eliminates fonts issues when using the PDF reader. False reduces the file size but might cause font issues. |
| page=<pagenum> | For reports, selects a page to print (width and height must be specified). For example, the pagenum can be "1-1", "2b", or "3". |
|
delim=tab |
Sets the output delimiter to be an ASCII tab. This option is applicable to text output only. |
| delim=comma | Sets the output delimiter to be a comma. This option is applicable to text output only. |
| delim=<character> | Sets the output delimiter to be the specified character. This option is applicable to text output only. |
| include_totals | Includes the totals row in the output. This option is applicable to text output and xls or xlsx output only. |
| imagemap=<filemap> | Produces an image-map file which corresponds to the output image. This option is applicable to image output only (jpeg and png files). If this option is supplied, the maptemplate parameter must be passed. |
NOTES:
- If a Marker is saved with QuickView values selected, re-opening the Marker displays the data with the QuickViews set to the selected values, rather than “All Values”.
- When run from a project, the marker.save_report, save_text, and save_window commands point to a temporary folder in the DiveLine dataroot (that is, dl-dataroot/temp).
- If when using the marker.print command, you specify a printer name that DIAL does not know, the error text includes a list of valid printers that are defined on the system.
Marker Examples
The following examples demonstrate Marker function usage.
NOTE: The marker.save_window points to a temp folder in the DiveLine dataroot (that is, dl-dataroot/temp).
Example 1
The following script opens test_marker.mrk and saves the bottom-most window in a 500x400 pixel jpeg file called window_test_marker.jpg in the dl-datroott/temp folder.
diveline.connect("myserver", "dial_user");
diveline.set_project("myProject");
console.writeln("Opening and saving marker to JPEG...");
marker.open(marker,"/models/test_marker.mrk");
marker.save_window(marker,"../temp/window_test_marker.jpg","jpeg,width=500,height=400");
diveline.disconnect();
Example 2
The following script opens the test_marker.mrk marker and saves its bottom-most window in a tab-delimited text file called window_test_marker.txt in the dl-dataroot/temp folder.
diveline.connect("myserver", "dial_user");
diveline.set_project("myProject");
console.writeln("Opening and saving marker to TEXT...");
marker.open(marker,"/models/test_marker.mrk");
marker.save_window(marker,"../temp/window_test_marker.txt", "txt");
diveline.disconnect();
Example 3
The following script opens the test_marker.mrk marker and saves its bottom-most window in a pdf file called window_test_marker.pdf in the dl-dataroot/temp folder.
diveline.connect("myserver", "dial_user");
diveline.set_project("myProject");
console.writeln("Opening and saving marker to PDF...");
marker.open(marker,"/models/test_marker.mrk");
marker.save_window(marker,"../temp/window_test_marker.pdf", "pdf");
diveline.disconnect();
Example 4
The following script opens the test_marker.mrk marker and saves its bottom-most window in an html file called window_test_marker.html in the dl-dataroot/temp folder.
diveline.connect("myserver", "dial_user");
diveline.set_project("myProject");
console.writeln("Opening and saving marker to HTML...");
marker.open(marker, "/models/test_marker.mrk");
marker.save_window(marker, "../temp/window_test_marker.html", "html");
diveline.disconnect();
Example 5: For arrays
This example uses the marker.open() syntax that specifies array key and value parameters. When specified, the dive_keys and dive_values arrays set QuickView and Parent window selections while the Marker is being opened.
For example, if the user has a Marker with Sales Region and Salesperson QuickViews, the following commands open the Marker and select North and Smith, respectively, for those QuickViews:
keys = array.new();
vals = array.new();
array.add(keys, "Sales Region");
array.add(vals, "North");
array.add(keys, "Salesperson");
array.add(vals, "Smith");
marker.open(mrk, "the-marker.mrk", keys, vals);