Structured Comments
Structured Comments are an extension to your SQL programming
which is
unique to SQL Explorer. By adding specially formatted
comments to your code you can communicate special instructions or tasks to SQL Explorer in a repeatable, scriptable manner; for example, you can:
- Use Macro Substitution to define a constant value once and have it used everywhere in your code
- Use Conditional Compilation to vary the code deployed to the server, EG to enable debugging globally
- Define input and output Parameters in calls to stored procedures
- Set Logging Parameters
- Cause SQLExplorer to prompt the user interactively for values (not yet implemented, see v3.5.0.beta3)
- Export and import data from local files (not yet implemented, see v3.5.0.beta3)
- Perform client-side JavaScript (not yet implemented, see v4.0.0)
The design of Structured Comments is such that using these
extensions,
while specific to SQL Explorer, will not make your code incompatible
with other tools (including those that came out-of-the-box with your
database product). This is because the commands are embeded
inside specially formatted comments which (because they are comments)
will be ignored by other products. The commands allow you to
define defaults and alternatives so that when your script is executed
by another tool they can have a sensible default behaviour, and it's
only when SQL Explorer runs them that they have special meaning.
Structured Comment Syntax
A Structured Comment consists of "${" at the very start
of a comment - no spaces should appear between the comment start and the "${". For single line comments (--) a
single space is allowed between the "--" and the "${" because some database systems require a space after "--" to
detect it as a single line comment.
For example:
/*${define mymacro} 12345*/
--${define mymacro2} 12345
-- ${define mymacro3} 12345
|
Correct |
/* ${define mymacro} */
-- ${define mymacro2} 12345
|
Incorrect |
Once SQL Explorer has identified a comment as a Structured Comment, it
then looks for a command and parameters in the following form:
${ command [parameter [parameter [...]] } [data]
I.E., the "${" at the start of the comment, followed by a
command, zero or more parameters, and then a "}"; after this
can optionally come some arbitrary data - we'll see how this can be
used later.
In the example above, the command is "define", it is given a parameter
of "mymacro", and has "12345" as the data; it's not hard to
guess that this Structured Comment defines a macro named "mymacro" and
sets it's value to "12345"!
Inline vs. Grouped Commands
Most Structured Comment commands are inline, which is to say that they
exist in a single comment; however, some commands span several
comments, similar to begin...end constructs in programming languages
(called a Grouped command). Typically, whether a command is
inline or grouped depends on how you use it; for example, the ifdef command is an inline command if you provide non-whitespace after the "}" but grouped if not. For example:
--${ifdef DEBUG} this is an inline ifdef
--$(ifdef !DEBUG}
this is a grouped ifdef
--${endif}