Each script displayed by SQL Scripts Manager is defined by an XML script file with extension .rgtool. You can locate and list these script files in Windows Explorer by selecting File > Show Scripts Folder from the SQL Scripts Manager menu.

Before you can use your own native-language scripts with SQL Scripts Manager (for example, SQL scripts), you need to embed your script code into an XML script file that has the correct structure, and that uses valid values for each XML element and attribute.

Worked example: adding your own scripts to SQL Scripts Manager describes the basic process of creating an XML script file around your script code.

This page, along with Types of control, provide detailed information on the "schema" (structure, elements, attributes, and values) for a valid _.rgtool _XML script file.

Structure of an .rgtool XML script file

The code below shows the basic structure of a valid .rgtool XML script file:

• [variable] shows where you must supply your own data (for example, [script description])
• [...] shows that the preceding tag pair can be repeated (for example, multiple <tag></tag> lines are valid)
• {value1|value2} shows where one or more literal strings must be used (for example, {Grid|OutputLog|ForceLog}). Read the description for an element or attribute for further information.

<?xml version="1.0" encoding="utf-8"?>
  <tool version="1">
    <description name="[script name]" icon="[name or .ico file]" version="[version id]" url="[script home page]">
      [script description]
    </description>
    <author name="[author name]" url="[author home page]" img="[author picture]" twitter="[user name]" />
    <tags>
      <tag>[tag name]</tag>
      [...]
    </tags>
    <ui>
      <output displaytype="{Grid|OutputLog|ForceLog}" width="[pixels]" height="[pixels]" />
      <block column="{None|Left|Center|Right}">
        <control type="{see Types of control}" id="[control identifier]" label="[UI string]">
          [...control-specific elements...]
        </control>
        [...]
      </block>
      [...]
    </ui>
    <presets>
      <default id="[control identifier]">
        <value>
          [default value]
        </value>
      </default>
      [...]
    </presets>
    <includes>
      <include file="[file name]" />
      [...]
    </includes>
    <script type="{sql|python|powershell}">
      [script content]
    </script>
    <signature>[signature key]</signature>
</tool>

List of .rgtool XML elements

<author>

<block>

<control>

<default>

<includes> and <include>

<output>

<presets>

<script>

<signature>

<tags> and <tag>

<tool>

<ui>

<value>

<tool> [required]

The top-level element (root node) in a script file. All content following the xml declaration (<?xml...) must be contained by <tool>...</tool> tags.

Attributes

• version [required]
  The version number of the script file format. The script file version number for this version of SQL Scripts Manager, is always "1".

[required]

A description of the script. The description text is used in the following places by SQL Scripts Manager:

• The first line of the description is shown:
  
  • under the script name on the main SQL Scripts Manager window
  • in the script's "Run" form
• The full description is shown on the Description tab of the script details window.

The description text can include simple HTML tags (for example, <i>, <b>, <ul>, <li>, <h1>, h2>, <pre>) for formatting the text on the Description tab.

Use the description text to provide users with an overview of what the script does, including any warnings and important information they should be aware of before running the script.

Attributes

• name [required]The name of the script. This is used throughout SQL Scripts Manager.

• icon [required]The icon used to represent the script in SQL Scripts Manager. This can be the file name of an .ico file that is located in the same folder as the script file, or you can specify the name of an icon distributed with SQL Scripts Manager, as listed below:

  Icon	Name	Icon	Name
  	chart_bar		data_out
  	data_copy		data_unknown
  	data_floppy_disk		key_warning
  	data_gear		recycle_ok
  	data_into		server_network
  	data_next		table2_information
  	data_ok		view

• _version [optional]The version of the script (for example, "v2.1").
• url [optional]A URL (http web address) offering support and further information about the script.

<author> [optional]

Information about the script's author. The author's name is shown in the main SQL Scripts Manager window. Other author information (home page url, twitter user name, and photo) is shown on the Author tab of the script details window.

Attributes

• name [required]The name of the author.
• url [optional]A URL (http web address) for the author's home page (for example, the author's blog).
• twitter [optional]Twitter user name for the author.
• img [optional]A reference to an image file containing a photo of the author. This can be:
  
  • a file name for an image file located in the same folder as the script file
  • a URL (http web address) pointing to an online image file

<tags> [required] and <tag> [at least one required]

SQL Scripts Manager uses tags to help users organize their scripts. Individual tags are shown in the main SQL Scripts Manager window, and can be used to filter the list of scripts.

You must provide at least one <tag> name within the <tags> list. You can specify multiple tags if necessary.

<tag> names can include any text. However, single-word tags are preferable.

Example:

<tags>
<tag>Backup</tag>
<tag>Diagnostic</tag>
</tags>

<ui> [required]

A container for the definition of the script's user interface (contains <output> and <block> elements).

<output> [required]

Specifies how the output from the script should be presented to the user in the Results window.

Attributes

• displaytype [required]Specifies the type of output to display in the Results window:

  Value	Description
  Grid	Displays results in a table. If the script produces more than one results set, all sets are displayed as a single table.
  OutputLog	Displays the textual output of the script. The text field shown in the Results window is collapsed by default.
  ForceLog	Displays the textual output of the script. The text field shown in the Results window is expanded by default.

  
  You can specify both 'Grid' _and one other value for displaytype, separated by a pipe symbol '|'; for example, 

   'displaytype="Grid | OutputLog"'

<block> [required]

Blocks are used to group <control> elements together. By positioning blocks (using the column attribute) you can control how a script's user interface is arranged.

Blocks are arranged in a grid pattern on the user interface. Each block corresponds to one column; specifying 'left' or 'right' for the column attribute, creates a two-column grid.

Attributes

• column [optional]

  Value	Description
  none	(Default) If you specify a single block, 'none' is equivalent to omitting the column attribute. The block will use the full width of the user interface.
  left	Adds a block on the left of the user interface. If a 'right' block is not specified, the right-hand column is left blank.
  right	Adds a block on the right of the user interface. If a 'left' block is not specified, the left-hand column is left blank.
  center	Adds a block in the middle of the user interface. If either a 'left' or a 'right' block already exists, the 'center' block will span both columns.

<control> [required]

A control is an individual user interface element (for example, a check box, list box, or folder browser).

You can access the value of each control from your script code (see <script>).

For full details of all control types, including other control attributes, see Types of control.

<presets> [optional]

A container for setting the default values of controls on the script's user interface (contains <default> elements).

<default> [optional]

Specifies a control that has a default value (contains <value> element).

Attributes

• id [required]The control id to associate with the default value.

<value> [optional]

The value to use for the default (for the control specified in the <default> element).

<includes> [optional] and <include> [at least one required]

You can include extra script code (in addition to the code specified by the <script> element) by adding an <includes> element to your script file.

The <includes> element contains one or more <include> elements, each of which specifies a file name to be included in the main script code.

Attributes (for <include> element)

• file [required]The name of the file to include (for example: <include file="support_code.sql" />)

<script> [required]

The script code that executes when the script is run from SQL Scripts Manager.

Attributes

• type [required]The type of script code:
   

  Value	Description
  sql	The script code is run using the SQL runner.
  python	The script code is run using the IronPython runner.
  powershell	The script code is run using the PowerShell runner.

Using control values in script code

If you have defined controls for your script's user interface (for example, text boxes), you will probably want to use the current values of those controls in your script code.

The method for accessing control values differs between SQL script code, and Python script code. To return the value of a control with id 'control_identifer':

• for SQL script code, use '@control_identifier' to return the value of the control

• for Python script code, use 'RedGate.control_identifier' to return the value of the control

  Your Python script code must begin with the line 'import RedGate', otherwise you will not be able to access control values.

<signature> [required]

Script files can be signed to guarantee authenticity.

For your own script files, leave the contents of the signature element blank, like this: <signature></signature>