<!-- pragma [push|pop] name [value] -->
<!-- pragma if expr -->
<!-- pragma elif expr -->
<!-- pragma else -->
<!-- pragma endif -->
pragma directive, unlike any other directive, can appear
anywhere in the script, including inside a function. Pragmas
typically alter the way code is lexically analyzed, so that the pragma
can be applied only to certain code sections if desired. Since they
appear in comments, earlier Vortex versions that are not aware of a
particular pragma will ignore them silently (unless
--warn-unknown-pragma is in effect,
here). The pragmas available are:
strictcomment on|offTurn on or off strict comment parsing. With strict comments on, comments must start with "
<!--", not just "
<!"; thus tags such as "
<!DOCTYPE>" are directly printable and do not get interpreted as comments. The default is on. Added in version 3.01.986950000 20010410.
nestcomment on|offTurn on or off nesting of comments. With nesting on, comments may be nested. The default is off. Added in version 3.01.986950000 20010410.
literalprint on|offWhether to allow literal text and/or variable printing. With literal printing off, printing text or variables by simply placing literal text or $-var references in the code is not allowed and will generate the compile error "Literal/variable printing not allowed when pragma literalprint off". Whitespace is still allowed but is silently ignored (instead of being output where not part of indentation); comments are also still permitted and ignored.
Turning off literal printing can be useful in some situations -
such as when generating an image - to ensure that all output
is being generated by explicit code, e.g. via
<fmt>, and no
inadvertent whitespace or mistyped code is causing extraneous
output, e.g. calls to non-existent functions being interpreted
as literal tags.
The default is on. Added in version 5.01.1223689000 20081010.
compilesqlexpressions on|offWhether to compile SQL expressions into the
.vscobject file where possible, rather than interpret them on the fly at run-time. SQL expressions are used in parenthetical variable assignments (e.g. <$x = ($y + 5)>) and complex
<if>statements, amongst other places. Compiling them speeds up script execution, as the original expression then does not need to be re-interpreted by the SQL engine every time the statement is run. The default is the value of the
texis.inisetting [Texis] Compile SQL Expressions; if that is unset, the default is on. Added in version 6.01.
Sets the version (major, optional minor, and optional release) of Texis to attempt Vortex script syntax compatibility with. The valid values are 7 through the version of the Texis executable. Currently only the major version number has any effect.
This setting controls various legacy functionality and
idiosyncrasies that have been fixed or changed in recent releases.
It affects SQL expressions (in
<while>, and variable assignments), especially quoted
strings and "$" in quoted strings; most loopable
</local> tags. (The -translate-from-version option
- here - attempts to handle some
of these changes, as noted below; it is preferable to
translate/update a script rather than use the
pragma, which may be deprecated in the future.)
syntaxversion is set to less than 8 (e.g. 7),
deprecated/old behavior is in effect. This includes:
<while>statements, or in single-quoted SQL literal strings in the SQL of
<sql>statements. Hence $$ and $var mean $$ and $var in those circumstances, not $ and (illegal) variable-parameter as they would in quoted strings in non-SQL-expression statements, which is inconsistent. For example, <$x = (stringformat( "price: %s" $$19.95" ))> would set the variable $x to a string with two - not one - dollar signs. Thus the parsing of $rank or $$rank in SQL expression statements could be affected. --translate-from-version attempts to fix this.
<export>etc. consisting solely of a variable (e.g. "$var" with quotes) are allowed (and are taken as a variable), instead of causing an Argument must be single variable or literal error (as most any other variable embedded in a quoted string would be, e.g. "foo$var"). Note also that since
<sql>is the only statement to allow embedded variables in its argument(s) (for SQL parameters), and can take its SQL statement as a variable, <sql "$stmt"> takes the $stmt variable as the SQL statement if version 7 syntax, but as a SQL parameter (to an empty SQL statement) if version 8 or later.-translate-from-version attempts to fix this.
<while>expressions - i.e. operand op operand where op is relational,
/- are evaluated by Vortex, not Texis SQL, and
<sqlcp arrayconvert>(here) does not apply (e.g. only the first value of multi-value variables in expressions will be used). Also, a string-token operand is permitted to be unquoted as in HTML. With version 8 or later syntax, all expressions are evaluated by Texis SQL, array conversion always applies, and string tokens must be quoted (for SQL).
<switch>value must be a single value or literal, not a Texis SQL expression, and
<sqlcp arrayconvert>(here) does not apply (nor does it in
<case>). With version 8 or later syntax, a Texis SQL (i.e.
SELECT) expression may be used in
arrayconvertapplies to both
<calrule>, resulting in a compile error such as "</LOCAL> with <LOCAL>" and/or "unterminated <stat> here".
<calrule>); some are looping if certain options are given (
<nslookup>); and others are always looping (
<readln>). All default to accumulating values in returned variables (i.e.
ROWis accepted, and defaults to off), and can be non-looping in version 7 or later if self-closed (e.g. "<sql ... />"). With
syntaxversion8 or more, version 8+ syntax is used: all loopable statements are non-looping if self-closed, looping otherwise (regardless of options or close tag), and return values never accumulate in looping versions (thus
ROWis redundant and not accepted). The exceptions to all of this are
<while>, which are always looping and do not change with this pragma. --translate-from-version attempts to fix loopable statements, and may warn if non-
ROWbehavior was used.
<xtree>behavior changes (in addition to looping changes above) for version 7 syntax:
GET) cannot be performed in the looping syntax
<fetch>behavior changes (in addition to looping changes above) for version 7 syntax:
PARALLELis not allowed for non-looping syntax (while allowed in version 8+ syntax, it is ignored: single fetch), and is required for looping syntax
RAWDOCattribute name is not allowed; the raw doc must be given as an arg after the URL, and only for non-looping syntax
URL[S], but must be after all other options
<nslookup>syntax changes (in addition to looping changes above) for version 7 syntax:
PARALLELflag determines loopiness
BYNAMEflags are allowed
BYNAMEare disallowed as redundant, as the $hostOrIp argument must be labelled
<readln>syntax changes (in addition to looping changes above) for version 7 syntax:
$ret.sizeare not set
OFFSEToption is not available
<stat>changes (in addition to changes above) for version 7 syntax:
$ret.groupidare not set
RESOLVEUSERNAMESflag is not available, but is implicitly on
$ret; in version 8 syntax, it is left unaltered.
<return>statement does not take a parenthetical expression as a SQL expression, nor may multiple values be given, in version 7 syntax.
$ret.msgvariables are not set in version 7 syntax.
The default for the
syntaxversion pragma is the value of
the --translate-from-version option
(here) if given; otherwise it
is the value of the texis.ini setting [Texis]
Compatibility Version (taking versions below 7 as 7). If
neither is set, the default is the version of the Texis
Caveat: Since Compatibility Version may change after the script is compiled, and thus change the default syntax version, changing Compatibility Version will force an automatic recompile of scripts when they are next run, so that the correct syntax version is always used.
Changing the value of this pragma in a script after an affected statement but before its associated end tag or enclosing block statement results in undefined behavior. This pragma should generally only be used at the top of a script.
Caveat: this pragma was added in version 8. Its supported version number range may change in a future release (e.g. version 7 will eventually be dropped), as older behavior is deprecated. Its existence is only to ease transition of old code when upgrading to Texis version 8 or later, and thus should only be used temporarily. Old code should be updated to reflect version 8 behavior - and this pragma removed from code - soon after upgrading.
if value [op value]
elif value [op value]
value op value expression is evaluated, and if true,
code following (up to the next matching
endif pragma) is compiled normally; if false, the code is
ignored. This provides a way to conditionally include code,
e.g. depending on Texis version.
value is interpreted as an integer. It may be a
literal integer, or one of the following tokens:
texisVersionMajorThe major version of Texis
texisVersionMinorThe minor version of Texis
texisReleaseDateThe Texis GMT release date, as an 8-digit YYYYMMDD integer
syntaxVersionMajorThe major version of
syntaxversion(here) currently in effect
syntaxVersionMinorThe minor version of
syntaxversioncurrently in effect
Any other token is silently (unless
--warn-all is used,
here) taken as 0. This allows an
older version of Texis to test for a feature token it knows
nothing about (i.e. from a future release), without causing a
compile error. (Production/release compilations, however, should
--warn-all to detect typos or incorrect uses of tokens.)
op is one of the relational operators < <= = !=
>= >. Alternatively, the entire expression may just be a
value, in which case it is true if the
is nonzero. The
elif pragma provides a way to combine
else and an
if without additional nesting.
Since (as of version 7.07.1612305160 20210202) Vortex scripts are
automatically recompiled whenever the Texis release changes (not
just when the Vortex compiled object file format changes, as in
previous versions), a script with an
if pragma that uses
e.g. texisReleaseDate will execute the correct
block even when a newer Texis executes a script compiled by an
older Texis (assuming both are version 8 or later).
Added in version 8.
In version 7 and later, pragmas
can be pushed or popped on a stack.
Pushing a pragma sets the value given, but first preserves the current
value; popping restores that previous value. Pushes may be nested to
any depth. This allows local sections of code to alter a pragma's
value, while still preserving and restoring the outer code's value
(without needing external "magic" knowledge of what it is):
literalprint could be on or off here (original value)
<!-- pragma push literalprint off -->
<!-- literalprint is off here -->
<!-- pragma pop literalprint -->
literalprint is back to its original value
Each pragma has its own independent stack, which starts out empty
(causing the pragma's default value to be in effect). A normal pragma
"set" directive (i.e. a pragma with neither
pop) acts as a
pop (if stack is not empty), followed by
push. It is an error to explicitly
pop a pragma when
its stack is empty.
Pragmas are in effect only for the
<script> block they appear
in, i.e. they are reset (stack cleared) for each new
block or module.
In this example, nestable comments are turned on. Thus the "
print bio of author" comment, which is inside a larger
comment, nests properly, and the entire inner
is commented out:
<!-- pragma nestcomment on -->
<SQL "select Title, Author from books
where Keywords like $query">
Title: $Title <!-- print title -->
Author: $Author <!-- print author -->
<!-- this section commented out:
<SQL "select Details from author
where Author = $Author">
Bio: $Details <!-- print bio of author -->