Using Report Studio

This is a basic introduction to Report Studio. You can also view the Advanced Report Studio help topic.

Why Use Report Studio?

Use Report Studio to write and test if macros work correctly before you use them in a report. If they don't work as expected, you will see immediate feedback and can tweak them and try again. Type in the left hand pane of Report Studio, see results in the adjacent pane and when a macro is running, see progress at the bottom.

If you open a .rmscript file (for example that you've written in Visual Studio Code), you'll see the colour coding in Report Studio:

Saving Your Work

Report Studio automatically saves your work at regular intervals in the background whenever changes are detected. You do not need to enable this - it happens automatically.

A dot in the toolbar, after the Help button, shows whether your work is saved. It is amber while the editor holds changes that are not saved yet, and green when it does not. With a file open, it stays amber until you save the file. With no file open, it turns green once your work has been auto-saved, and its ring widens for a moment as each auto-save lands. Hover over it to see when your work was last auto-saved.

If you attempt to navigate away, open a different file, or create a new document while you have unsaved changes, Report Studio will ask you to confirm before discarding your work.

To save manually:

  • Save (Ctrl+S) - overwrites the current file. If no file is open, you will be prompted to choose a location
  • Save As (Ctrl+Shift+S) - saves to a new location

To recover auto-saved content, from the File menu, click Restore Auto-Saved (Ctrl+Alt+R). The Restore dialog lists two kinds of snapshot together, grouped by day with the newest first:

  • Sessions - snapshots from free-form editing sessions where no file was open
  • Files - snapshots linked to a specific file you had open, marked with a file icon and the file's name. Restoring one loads the content and associates it with the original file, so saving will update that file

Each snapshot is listed by its first line, with how long ago it was saved, how many lines it has and its size. Hover over one to see exactly when it was saved. A snapshot of a Word document is listed by its file name.

  • Type in the search box to find a snapshot by its text or, for a file, by the file's name or folder
  • Use the drop-down beside the search box to see all snapshots, only sessions or only files
  • Click a snapshot to preview it. A script from Code mode is shown in a code editor with line numbers, and a rich-text report as it looks
  • Restore puts it in the editor, and Run puts it in the editor and runs it straight away
  • Copy copies its text to the clipboard without loading it
  • Delete deletes it, after asking you first, as a deleted snapshot cannot be brought back

When opening a file that has a more recent auto-save available, Report Studio will prompt you to load the newer version instead.

Recently Opened Files

Report Studio tracks the last 10 files you have opened or saved, kept apart from your recent files in SQL Studio and MQL Studio. To reopen one, use File > Open Recent (Ctrl+Alt+O).

The Recent Files dialog lists your recent files grouped by day, with the newest first. Each file is shown with its icon, its name and folder, and how long ago you opened it. Hover over one to see exactly when you opened it.

  • Type in the search box to find a file by any part of its name or folder
  • Click a file to preview it. A script is shown in a code editor with line numbers, and a rich-text report or Word document as it looks
  • Load opens it in the editor, and Run opens it and runs it straight away. Double-clicking a file also loads it
  • Copy copies its text to the clipboard without loading it
  • Remove from List takes it off your recent files. The file itself is not changed
  • A file that has been moved or deleted is marked Not found. It cannot be loaded, but you can remove it from the list

If a newer auto-save exists for the selected file, Report Studio will prompt you to load the auto-saved version instead.

Press F1 or the Help icon at any time to read more information.

Running a Macro in Report Studio

To try out a macro in Report Studio:

  1. Click Report Studio
  2. In the left hand pane, type the words "The hostname is"
  3. From the Report Studio Help menu, click Insert Example
  4. Expand the Core section and scroll until you find the String macro
  5. Click 5 to insert the 5th example. The example macro is pasted into the left pane
  6. Click the Run button. The String macro result is shown in the results pane

Saving a Template in Report Studio

Whether you've used some example macros or written your own from scratch in Report Studio, you can save your work as a template to use in a schedule. Please note table formatting is not copied when you save from Report Studio.

To save your work as a template to use in a schedule:

  1. Ensure you have created folders for your files
  2. In Report Studio, from the File menu, click Save As
  3. Select the required input folder
  4. Type a file name and enter the required extension
  5. Click Save

Using Code Mode

If you're used to a development environment, try Code mode by clicking the Code button, or using Ctrl+Alt+T. Code mode lets you paste from tools such as Visual Studio, while retaining indents, spacing and honouring comments - meaning anything prefixed with // will not appear in output. That you are in Code mode is evident from the numbered lines. Additionally, on the right, you'll see the code in miniature with an indication of where you are in it.

Click the Settings icon to choose, for new code only, to use spaces instead of the default of tabs. This is just a matter of personal choice. Type the number of spaces that you want to use instead of a tab.

To return to Rich Text, click the Rich Text button.

Storing Variables - Normal and Legacy Modes

A drop down in the toolbar changes how variables are stored. Normal Mode is recommended for all development:

In Normal mode, any variable you store will usually be saved as a specific type of object (int32, float, array, list, JObject, etc.). Normal mode is useful (and is the recommended approach) as it makes parsing results of macros much easier, when used as an input to other macros.

In Legacy mode, all variables are stored as strings. If you have very old reports, they may still be in Legacy mode.

Tips and Tricks

  • Use Insert Macro to search available macros and the parameters you can use. There are examples on every help page that you can paste into Report Studio
  • Use mode = legacy only in the rare circumstance you require a macro to produce Legacy output
  • Save your work regularly. If needed, use File > Restore Auto-Saved to browse and recover from auto-saved snapshots
  • Make it easy to find macros by using special macros like [Section:], [Comment:] and [Ignore:] to break up the Progress pane

Reconnection

Reconnection

Reconnection

timed out

timed out

Attempt of

Reload
An unhandled error has occurred. Reload 🗙